lisp/bookmark.el

   1 ;;; bookmark.el --- set bookmarks, maybe annotate them, jump to them later
   2
   3 ;; Copyright (C) 1993-1997, 2001-2012 Free Software Foundation, Inc.
   4
   5 ;; Author: Karl Fogel <kfogel@red-bean.com>
   6 ;; Maintainer: Karl Fogel <kfogel@red-bean.com>
   7 ;; Created: July, 1993
   8 ;; Keywords: bookmarks, placeholders, annotations
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26
  27 ;; This package is for setting "bookmarks" in files.  A bookmark
  28 ;; associates a string with a location in a certain file.  Thus, you
  29 ;; can navigate your way to that location by providing the string.
  30 ;; See the "User Variables" section for customizations.
  31
  32 \f
  33 ;;; Code:
  34
  35 (require 'pp)
  36 (eval-when-compile (require 'cl-lib))
  37
  38 ;;; Misc comments:
  39 ;;
  40 ;; If variable bookmark-use-annotations is non-nil, an annotation is
  41 ;; queried for when setting a bookmark.
  42 ;;
  43 ;; The bookmark list is sorted lexically by default, but you can turn
  44 ;; this off by setting bookmark-sort-flag to nil.  If it is nil, then
  45 ;; the list will be presented in the order it is recorded
  46 ;; (chronologically), which is actually fairly useful as well.
  47
  48 ;;; User Variables
  49
  50 (defgroup bookmark nil
  51   "Setting, annotation and jumping to bookmarks."
  52   :group 'matching)
  53
  54
  55 (defcustom bookmark-use-annotations nil
  56   "If non-nil, saving a bookmark queries for an annotation in a buffer."
  57   :type 'boolean
  58   :group 'bookmark)
  59
  60
  61 (defcustom bookmark-save-flag t
  62   "Controls when Emacs saves bookmarks to a file.
  63 --> nil means never save bookmarks, except when `bookmark-save' is
  64     explicitly called (\\[bookmark-save]).
  65 --> t means save bookmarks when Emacs is killed.
  66 --> Otherwise, it should be a number that is the frequency with which
  67     the bookmark list is saved (i.e.: the number of times which
  68     Emacs's bookmark list may be modified before it is automatically
  69     saved.).  If it is a number, Emacs will also automatically save
  70     bookmarks when it is killed.
  71
  72 Therefore, the way to get it to save every time you make or delete a
  73 bookmark is to set this variable to 1 (or 0, which produces the same
  74 behavior.)
  75
  76 To specify the file in which to save them, modify the variable
  77 `bookmark-default-file', which is `~/.emacs.bmk' by default."
  78   :type '(choice (const nil) integer (other t))
  79   :group 'bookmark)
  80
  81
  82 (defconst bookmark-old-default-file "~/.emacs-bkmrks"
  83   "The `.emacs.bmk' file used to be called this name.")
  84
  85
  86 ;; defvared to avoid a compilation warning:
  87 (defvar bookmark-file nil
  88   "Old name for `bookmark-default-file'.")
  89
  90 (defcustom bookmark-default-file
  91   (if bookmark-file
  92       ;; In case user set `bookmark-file' in her .emacs:
  93       bookmark-file
  94     (locate-user-emacs-file "bookmarks" ".emacs.bmk"))
  95   "File in which to save bookmarks by default."
  96   :type 'file
  97   :group 'bookmark)
  98
  99
 100 (defcustom bookmark-version-control 'nospecial
 101   "Whether or not to make numbered backups of the bookmark file.
 102 It can have four values: t, nil, `never', and `nospecial'.
 103 The first three have the same meaning that they do for the
 104 variable `version-control', and the final value `nospecial' means just
 105 use the value of `version-control'."
 106   :type '(choice (const nil) (const never) (const nospecial)
 107                  (other t))
 108   :group 'bookmark)
 109
 110
 111 (defcustom bookmark-completion-ignore-case t
 112   "Non-nil means bookmark functions ignore case in completion."
 113   :type 'boolean
 114   :group 'bookmark)
 115
 116
 117 (defcustom bookmark-sort-flag t
 118   "Non-nil means that bookmarks will be displayed sorted by bookmark name.
 119 Otherwise they will be displayed in LIFO order (that is, most
 120 recently set ones come first, oldest ones come last)."
 121   :type 'boolean
 122   :group 'bookmark)
 123
 124
 125 (defcustom bookmark-automatically-show-annotations t
 126   "Non-nil means show annotations when jumping to a bookmark."
 127   :type 'boolean
 128   :group 'bookmark)
 129
 130
 131 (defconst bookmark-bmenu-header-height 2
 132   "Number of lines used for the *Bookmark List* header.")
 133
 134 (defconst bookmark-bmenu-marks-width 2
 135   "Number of columns (chars) used for the *Bookmark List* marks column,
 136 including the annotations column.")
 137
 138 (defcustom bookmark-bmenu-file-column 30
 139   "Column at which to display filenames in a buffer listing bookmarks.
 140 You can toggle whether files are shown with \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-toggle-filenames]."
 141   :type 'integer
 142   :group 'bookmark)
 143
 144
 145 (defcustom bookmark-bmenu-toggle-filenames t
 146   "Non-nil means show filenames when listing bookmarks.
 147 A non-nil value may result in truncated bookmark names."
 148   :type 'boolean
 149   :group 'bookmark)
 150
 151
 152 (defcustom bookmark-menu-length 70
 153   "Maximum length of a bookmark name displayed on a popup menu."
 154   :type 'integer
 155   :group 'bookmark)
 156
 157 ;; FIXME: Is it really worth a customization option?
 158 (defcustom bookmark-search-delay 0.2
 159   "Time before `bookmark-bmenu-search' updates the display."
 160   :group 'bookmark
 161   :type  'integer)
 162
 163 (defface bookmark-menu-heading
 164   '((t (:inherit font-lock-type-face)))
 165   "Face used to highlight the heading in bookmark menu buffers."
 166   :group 'bookmark
 167   :version "22.1")
 168
 169
 170 ;;; No user-serviceable parts beyond this point.
 171
 172 ;; Added  for lucid emacs  compatibility, db
 173 (or (fboundp 'defalias)  (fset 'defalias 'fset))
 174
 175 ;; suggested for lucid compatibility by david hughes:
 176 (or (fboundp 'frame-height)  (defalias 'frame-height 'screen-height))
 177
 178 \f
 179 ;;; Keymap stuff:
 180
 181 ;; Set up these bindings dumping time *only*;
 182 ;; if the user alters them, don't override the user when loading bookmark.el.
 183
 184 ;;;###autoload (define-key ctl-x-r-map "b" 'bookmark-jump)
 185 ;;;###autoload (define-key ctl-x-r-map "m" 'bookmark-set)
 186 ;;;###autoload (define-key ctl-x-r-map "l" 'bookmark-bmenu-list)
 187
 188 ;;;###autoload
 189 (defvar bookmark-map
 190   (let ((map (make-sparse-keymap)))
 191     ;; Read the help on all of these functions for details...
 192     (define-key map "x" 'bookmark-set)
 193     (define-key map "m" 'bookmark-set) ;"m"ark
 194     (define-key map "j" 'bookmark-jump)
 195     (define-key map "g" 'bookmark-jump) ;"g"o
 196     (define-key map "o" 'bookmark-jump-other-window)
 197     (define-key map "i" 'bookmark-insert)
 198     (define-key map "e" 'edit-bookmarks)
 199     (define-key map "f" 'bookmark-insert-location) ;"f"ind
 200     (define-key map "r" 'bookmark-rename)
 201     (define-key map "d" 'bookmark-delete)
 202     (define-key map "l" 'bookmark-load)
 203     (define-key map "w" 'bookmark-write)
 204     (define-key map "s" 'bookmark-save)
 205     map)
 206   "Keymap containing bindings to bookmark functions.
 207 It is not bound to any key by default: to bind it
 208 so that you have a bookmark prefix, just use `global-set-key' and bind a
 209 key of your choice to `bookmark-map'.  All interactive bookmark
 210 functions have a binding in this keymap.")
 211
 212 ;;;###autoload (fset 'bookmark-map bookmark-map)
 213
 214 \f
 215 ;;; Core variables and data structures:
 216 (defvar bookmark-alist ()
 217   "Association list of bookmarks and their records.
 218 Bookmark functions update the value automatically.
 219 You probably do NOT want to change the value yourself.
 220
 221 The value is an alist with entries of the form
 222
 223  (BOOKMARK-NAME . PARAM-ALIST)
 224
 225 or the deprecated form (BOOKMARK-NAME PARAM-ALIST).
 226
 227  BOOKMARK-NAME is the name you gave to the bookmark when creating it.
 228
 229  PARAM-ALIST is an alist of bookmark information.  The order of the
 230  entries in PARAM-ALIST is not important.  The possible entries are
 231  described below.  An entry with a key but null value means the entry
 232  is not used.
 233
 234   (filename . FILENAME)
 235   (position . POS)
 236   (front-context-string . STR-AFTER-POS)
 237   (rear-context-string  . STR-BEFORE-POS)
 238   (handler . HANDLER)
 239   (annotation . ANNOTATION)
 240
 241  FILENAME names the bookmarked file.
 242  POS is the bookmarked buffer position (position in the file).
 243  STR-AFTER-POS is buffer text that immediately follows POS.
 244  STR-BEFORE-POS is buffer text that immediately precedes POS.
 245  ANNOTATION is a string that describes the bookmark.
 246    See options `bookmark-use-annotations' and
 247    `bookmark-automatically-show-annotations'.
 248  HANDLER is a function that provides the bookmark-jump behavior for a
 249  specific kind of bookmark.  This is the case for Info bookmarks,
 250  for instance.  HANDLER must accept a bookmark as argument.")
 251
 252 (defvar bookmarks-already-loaded nil
 253   "Non-nil if and only if bookmarks have been loaded from `bookmark-default-file'.")
 254
 255
 256 ;; more stuff added by db.
 257
 258 (defvar bookmark-current-bookmark nil
 259   "Name of bookmark most recently used in the current file.
 260 It is buffer local, used to make moving a bookmark forward
 261 through a file easier.")
 262
 263 (make-variable-buffer-local 'bookmark-current-bookmark)
 264
 265
 266 (defvar bookmark-alist-modification-count 0
 267   "Number of modifications to bookmark list since it was last saved.")
 268
 269
 270 (defvar bookmark-search-size 16
 271   "Length of the context strings recorded on either side of a bookmark.")
 272
 273
 274 (defvar bookmark-current-buffer nil
 275   "The buffer in which a bookmark is currently being set or renamed.
 276 Functions that insert strings into the minibuffer use this to know
 277 the source buffer for that information; see `bookmark-yank-word'
 278 for example.")
 279
 280
 281 (defvar bookmark-yank-point 0
 282   "The next point from which to pull source text for `bookmark-yank-word'.
 283 This point is in `bookmark-current-buffer'.")
 284
 285
 286 (defvar bookmark-quit-flag nil
 287   "Non nil make `bookmark-bmenu-search' quit immediately.")
 288 \f
 289 ;; Helper functions and macros.
 290
 291 (defmacro with-buffer-modified-unmodified (&rest body)
 292   "Run BODY while preserving the buffer's `buffer-modified-p' state."
 293   (let ((was-modified (make-symbol "was-modified")))
 294     `(let ((,was-modified (buffer-modified-p)))
 295        (unwind-protect
 296            (progn ,@body)
 297          (set-buffer-modified-p ,was-modified)))))
 298
 299 ;; Only functions below, in this page and the next one (file formats),
 300 ;; need to know anything about the format of bookmark-alist entries.
 301 ;; Everyone else should go through them.
 302
 303 (defun bookmark-name-from-full-record (bookmark-record)
 304   "Return the name of BOOKMARK-RECORD.  BOOKMARK-RECORD is, e.g.,
 305 one element from `bookmark-alist'."
 306   (car bookmark-record))
 307
 308
 309 (defun bookmark-all-names ()
 310   "Return a list of all current bookmark names."
 311   (bookmark-maybe-load-default-file)
 312   (mapcar 'bookmark-name-from-full-record bookmark-alist))
 313
 314
 315 (defun bookmark-get-bookmark (bookmark-name-or-record &optional noerror)
 316   "Return the bookmark record corresponding to BOOKMARK-NAME-OR-RECORD.
 317 If BOOKMARK-NAME-OR-RECORD is a string, look for the corresponding
 318 bookmark record in `bookmark-alist'; return it if found, otherwise
 319 error.  Else if BOOKMARK-NAME-OR-RECORD is already a bookmark record,
 320 just return it."
 321   (cond
 322    ((consp bookmark-name-or-record) bookmark-name-or-record)
 323    ((stringp bookmark-name-or-record)
 324     (or (assoc-string bookmark-name-or-record bookmark-alist
 325                       bookmark-completion-ignore-case)
 326         (unless noerror (error "Invalid bookmark %s"
 327                                bookmark-name-or-record))))))
 328
 329
 330 (defun bookmark-get-bookmark-record (bookmark-name-or-record)
 331   "Return the record portion of the entry for BOOKMARK-NAME-OR-RECORD in
 332 `bookmark-alist' (that is, all information but the name)."
 333   (let ((alist (cdr (bookmark-get-bookmark bookmark-name-or-record))))
 334     ;; The bookmark objects can either look like (NAME ALIST) or
 335     ;; (NAME . ALIST), so we have to distinguish the two here.
 336     (if (and (null (cdr alist)) (consp (caar alist)))
 337         (car alist) alist)))
 338
 339
 340 (defun bookmark-set-name (bookmark-name-or-record newname)
 341   "Set BOOKMARK-NAME-OR-RECORD's name to NEWNAME."
 342   (setcar (bookmark-get-bookmark bookmark-name-or-record) newname))
 343
 344 (defun bookmark-prop-get (bookmark-name-or-record prop)
 345   "Return the property PROP of BOOKMARK-NAME-OR-RECORD, or nil if none."
 346   (cdr (assq prop (bookmark-get-bookmark-record bookmark-name-or-record))))
 347
 348 (defun bookmark-prop-set (bookmark-name-or-record prop val)
 349   "Set the property PROP of BOOKMARK-NAME-OR-RECORD to VAL."
 350   (let ((cell (assq
 351                prop (bookmark-get-bookmark-record bookmark-name-or-record))))
 352     (if cell
 353         (setcdr cell val)
 354       (nconc (bookmark-get-bookmark-record bookmark-name-or-record)
 355              (list (cons prop val))))))
 356
 357 (defun bookmark-get-annotation (bookmark-name-or-record)
 358   "Return the annotation of BOOKMARK-NAME-OR-RECORD, or nil if none."
 359   (bookmark-prop-get bookmark-name-or-record 'annotation))
 360
 361 (defun bookmark-set-annotation (bookmark-name-or-record ann)
 362   "Set the annotation of BOOKMARK-NAME-OR-RECORD to ANN."
 363   (bookmark-prop-set bookmark-name-or-record 'annotation ann))
 364
 365
 366 (defun bookmark-get-filename (bookmark-name-or-record)
 367   "Return the full filename of BOOKMARK-NAME-OR-RECORD, or nil if none."
 368   (bookmark-prop-get bookmark-name-or-record 'filename))
 369
 370
 371 (defun bookmark-set-filename (bookmark-name-or-record filename)
 372   "Set the full filename of BOOKMARK-NAME-OR-RECORD to FILENAME."
 373   (bookmark-prop-set bookmark-name-or-record 'filename filename))
 374
 375
 376 (defun bookmark-get-position (bookmark-name-or-record)
 377   "Return the position (i.e.: point) of BOOKMARK-NAME-OR-RECORD, or nil if none."
 378   (bookmark-prop-get bookmark-name-or-record 'position))
 379
 380
 381 (defun bookmark-set-position (bookmark-name-or-record position)
 382   "Set the position (i.e.: point) of BOOKMARK-NAME-OR-RECORD to POSITION."
 383   (bookmark-prop-set bookmark-name-or-record 'position position))
 384
 385
 386 (defun bookmark-get-front-context-string (bookmark-name-or-record)
 387   "Return the front-context-string of BOOKMARK-NAME-OR-RECORD, or nil if none."
 388   (bookmark-prop-get bookmark-name-or-record 'front-context-string))
 389
 390
 391 (defun bookmark-set-front-context-string (bookmark-name-or-record string)
 392   "Set the front-context-string of BOOKMARK-NAME-OR-RECORD to STRING."
 393   (bookmark-prop-set bookmark-name-or-record 'front-context-string string))
 394
 395
 396 (defun bookmark-get-rear-context-string (bookmark-name-or-record)
 397   "Return the rear-context-string of BOOKMARK-NAME-OR-RECORD, or nil if none."
 398   (bookmark-prop-get bookmark-name-or-record 'rear-context-string))
 399
 400
 401 (defun bookmark-set-rear-context-string (bookmark-name-or-record string)
 402   "Set the rear-context-string of BOOKMARK-NAME-OR-RECORD to STRING."
 403   (bookmark-prop-set bookmark-name-or-record 'rear-context-string string))
 404
 405
 406 (defun bookmark-get-handler (bookmark-name-or-record)
 407   "Return the handler function for BOOKMARK-NAME-OR-RECORD, or nil if none."
 408   (bookmark-prop-get bookmark-name-or-record 'handler))
 409
 410 (defvar bookmark-history nil
 411   "The history list for bookmark functions.")
 412
 413
 414 (defun bookmark-completing-read (prompt &optional default)
 415   "Prompting with PROMPT, read a bookmark name in completion.
 416 PROMPT will get a \": \" stuck on the end no matter what, so you
 417 probably don't want to include one yourself.
 418 Optional second arg DEFAULT is a string to return if the user enters
 419 the empty string."
 420   (bookmark-maybe-load-default-file) ; paranoia
 421   (if (listp last-nonmenu-event)
 422       (bookmark-menu-popup-paned-menu t prompt
 423                                       (if bookmark-sort-flag
 424                                           (sort (bookmark-all-names)
 425                                                 'string-lessp)
 426                                         (bookmark-all-names)))
 427     (let* ((completion-ignore-case bookmark-completion-ignore-case)
 428            (default default)
 429            (prompt (concat prompt (if default
 430                                       (format " (%s): " default)
 431                                     ": ")))
 432            (str
 433             (completing-read prompt
 434                              bookmark-alist
 435                              nil
 436                              0
 437                              nil
 438                              'bookmark-history)))
 439       (if (string-equal "" str) default str))))
 440
 441
 442 (defmacro bookmark-maybe-historicize-string (string)
 443   "Put STRING into the bookmark prompt history, if caller non-interactive.
 444 We need this because sometimes bookmark functions are invoked from
 445 menus, so `completing-read' never gets a chance to set `bookmark-history'."
 446   `(or
 447     (called-interactively-p 'interactive)
 448     (setq bookmark-history (cons ,string bookmark-history))))
 449
 450 (defvar bookmark-make-record-function 'bookmark-make-record-default
 451   "A function that should be called to create a bookmark record.
 452 Modes may set this variable buffer-locally to enable bookmarking of
 453 locations that should be treated specially, such as Info nodes,
 454 news posts, images, pdf documents, etc.
 455
 456 The function will be called with no arguments.
 457 It should signal a user error if it is unable to construct a record for
 458 the current location.
 459
 460 The returned record should be a cons cell of the form (NAME . ALIST)
 461 where ALIST is as described in `bookmark-alist' and may typically contain
 462 a special cons (handler . HANDLER-FUNC) which specifies the handler function
 463 that should be used instead of `bookmark-default-handler' to open this
 464 bookmark.  See the documentation for `bookmark-alist' for more.
 465
 466 NAME is a suggested name for the constructed bookmark.  It can be nil
 467 in which case a default heuristic will be used.  The function can also
 468 equivalently just return ALIST without NAME.")
 469
 470 (defun bookmark-make-record ()
 471   "Return a new bookmark record (NAME . ALIST) for the current location."
 472   (let ((record (funcall bookmark-make-record-function)))
 473     ;; Set up defaults.
 474     (bookmark-prop-set
 475      record 'defaults
 476      (delq nil (delete-dups (append (bookmark-prop-get record 'defaults)
 477                                     (list bookmark-current-bookmark
 478                                           (bookmark-buffer-name))))))
 479     ;; Set up default name.
 480     (if (stringp (car record))
 481         ;; The function already provided a default name.
 482         record
 483       (if (car record) (push nil record))
 484       (setcar record (or bookmark-current-bookmark (bookmark-buffer-name)))
 485       record)))
 486
 487 (defun bookmark-store (name alist no-overwrite)
 488   "Store the bookmark NAME with data ALIST.
 489 If NO-OVERWRITE is non-nil and another bookmark of the same name already
 490 exists in `bookmark-alist', record the new bookmark without throwing away the
 491 old one."
 492   (bookmark-maybe-load-default-file)
 493   (let ((stripped-name (copy-sequence name)))
 494     (or (featurep 'xemacs)
 495         ;; XEmacs's `set-text-properties' doesn't work on
 496         ;; free-standing strings, apparently.
 497         (set-text-properties 0 (length stripped-name) nil stripped-name))
 498     (if (and (not no-overwrite)
 499              (bookmark-get-bookmark stripped-name 'noerror))
 500         ;; already existing bookmark under that name and
 501         ;; no prefix arg means just overwrite old bookmark
 502         ;; Use the new (NAME . ALIST) format.
 503         (setcdr (bookmark-get-bookmark stripped-name) alist)
 504
 505       ;; otherwise just cons it onto the front (either the bookmark
 506       ;; doesn't exist already, or there is no prefix arg.  In either
 507       ;; case, we want the new bookmark consed onto the alist...)
 508
 509       (push (cons stripped-name alist) bookmark-alist))
 510
 511     ;; Added by db
 512     (setq bookmark-current-bookmark stripped-name)
 513     (setq bookmark-alist-modification-count
 514           (1+ bookmark-alist-modification-count))
 515     (if (bookmark-time-to-save-p)
 516         (bookmark-save))
 517
 518     (setq bookmark-current-bookmark stripped-name)
 519     (bookmark-bmenu-surreptitiously-rebuild-list)))
 520
 521 (defun bookmark-make-record-default (&optional no-file no-context posn)
 522   "Return the record describing the location of a new bookmark.
 523 Point should be at the buffer in which the bookmark is being set,
 524 and normally should be at the position where the bookmark is desired,
 525 but see the optional arguments for other possibilities.
 526
 527 If NO-FILE is non-nil, then only return the subset of the
 528 record that pertains to the location within the buffer, leaving off
 529 the part that records the filename.
 530
 531 If NO-CONTEXT is non-nil, do not include the front- and rear-context
 532 strings in the record -- the position is enough.
 533
 534 If POSN is non-nil, record POSN as the point instead of `(point)'."
 535   `(,@(unless no-file `((filename . ,(bookmark-buffer-file-name))))
 536     ,@(unless no-context `((front-context-string
 537                            . ,(if (>= (- (point-max) (point))
 538                                       bookmark-search-size)
 539                                   (buffer-substring-no-properties
 540                                    (point)
 541                                    (+ (point) bookmark-search-size))
 542                                   nil))))
 543     ,@(unless no-context `((rear-context-string
 544                            . ,(if (>= (- (point) (point-min))
 545                                       bookmark-search-size)
 546                                   (buffer-substring-no-properties
 547                                    (point)
 548                                    (- (point) bookmark-search-size))
 549                                   nil))))
 550     (position . ,(or posn (point)))))
 551
 552 \f
 553 ;;; File format stuff
 554
 555 ;; *IMPORTANT NOTICE* If you are thinking about modifying (redefining)
 556 ;; the bookmark file format -- please don't.  The current format
 557 ;; should be extensible enough.  If you feel the need to change it,
 558 ;; please discuss it with other Emacs developers first.
 559 ;;
 560 ;; The format of `bookmark-alist' has changed twice in its lifetime.
 561 ;; This comment describes the three formats, FIRST, SECOND, and
 562 ;; CURRENT.
 563 ;;
 564 ;; The FIRST format was used prior to Emacs 20:
 565 ;;
 566 ;;       ((BOOKMARK-NAME (FILENAME
 567 ;;                          STRING-IN-FRONT
 568 ;;                          STRING-BEHIND
 569 ;;                          POINT))
 570 ;;        ...)
 571 ;;
 572 ;; The SECOND format was introduced in Emacs 20:
 573 ;;
 574 ;;       ((BOOKMARK-NAME ((filename   . FILENAME)
 575 ;;                        (position   . POS)
 576 ;;                        (front-context-string . STR-AFTER-POS)
 577 ;;                        (rear-context-string  . STR-BEFORE-POS)
 578 ;;                        (annotation . ANNOTATION)
 579 ;;                        (whatever   . VALUE)
 580 ;;                        ...
 581 ;;                       ))
 582 ;;        ...)
 583 ;;
 584 ;; The CURRENT format was introduced in Emacs 22:
 585 ;;
 586 ;;       ((BOOKMARK-NAME (filename   . FILENAME)
 587 ;;                       (position   . POS)
 588 ;;                       (front-context-string . STR-AFTER-POS)
 589 ;;                       (rear-context-string  . STR-BEFORE-POS)
 590 ;;                       (annotation . ANNOTATION)
 591 ;;                       (whatever   . VALUE)
 592 ;;                       ...
 593 ;;                       )
 594 ;;        ...)
 595 ;;
 596 ;; Both FIRST and SECOND have the same level of nesting: the cadr of a
 597 ;; bookmark record is a list of entry information.  FIRST and SECOND
 598 ;; differ in the form of the record information: FIRST uses a list of
 599 ;; atoms, and SECOND uses an alist.  In the FIRST format, the order of
 600 ;; the list elements matters.  In the SECOND format, the order of the
 601 ;; alist elements is unimportant.  The SECOND format facilitates the
 602 ;; addition of new kinds of elements, to support new kinds of
 603 ;; bookmarks or code evolution.
 604 ;;
 605 ;; The CURRENT format removes a level of nesting wrt FIRST and SECOND,
 606 ;; saving one cons cell per bookmark: the cadr of a bookmark record is
 607 ;; no longer a cons.  Why that change was made remains a mystery --
 608 ;; just be aware of it.  (Be aware too that this explanatory comment
 609 ;; was incorrect in Emacs 22 and Emacs 23.1.)
 610 ;;
 611 ;; To deal with the change from FIRST format to SECOND, conversion
 612 ;; code was added, and it is still in use.  See
 613 ;; `bookmark-maybe-upgrade-file-format'.
 614 ;;
 615 ;; No conversion from SECOND to CURRENT is done.  Instead, the code
 616 ;; handles both formats OK.  It must continue to do so.
 617 ;;
 618 ;; See the doc string of `bookmark-alist' for information about the
 619 ;; elements that define a bookmark (e.g. `filename').
 620
 621
 622 (defconst bookmark-file-format-version 1
 623   "The current version of the format used by bookmark files.
 624 You should never need to change this.")
 625
 626
 627 (defconst bookmark-end-of-version-stamp-marker
 628   "-*- End Of Bookmark File Format Version Stamp -*-\n"
 629   "This string marks the end of the version stamp in a bookmark file.")
 630
 631
 632 (defun bookmark-alist-from-buffer ()
 633   "Return a `bookmark-alist' (in any format) from the current buffer.
 634 The buffer must of course contain bookmark format information.
 635 Does not care from where in the buffer it is called, and does not
 636 affect point."
 637   (save-excursion
 638     (goto-char (point-min))
 639     (if (search-forward bookmark-end-of-version-stamp-marker nil t)
 640         (read (current-buffer))
 641       ;; Else we're dealing with format version 0
 642       (if (search-forward "(" nil t)
 643           (progn
 644             (forward-char -1)
 645             (read (current-buffer)))
 646         ;; Else no hope of getting information here.
 647         (error "Not bookmark format")))))
 648
 649
 650 (defun bookmark-upgrade-version-0-alist (old-list)
 651   "Upgrade a version 0 alist OLD-LIST to the current version."
 652   (mapcar
 653    (lambda (bookmark)
 654      (let* ((name      (car bookmark))
 655             (record    (car (cdr bookmark)))
 656             (filename  (nth 0 record))
 657             (front-str (nth 1 record))
 658             (rear-str  (nth 2 record))
 659             (position  (nth 3 record))
 660             (ann       (nth 4 record)))
 661        (list
 662         name
 663         `((filename             .    ,filename)
 664           (front-context-string .    ,(or front-str ""))
 665           (rear-context-string  .    ,(or rear-str  ""))
 666           (position             .    ,position)
 667           (annotation           .    ,ann)))))
 668    old-list))
 669
 670
 671 (defun bookmark-upgrade-file-format-from-0 ()
 672   "Upgrade a bookmark file of format 0 (the original format) to format 1.
 673 This expects to be called from `point-min' in a bookmark file."
 674   (message "Upgrading bookmark format from 0 to %d..."
 675            bookmark-file-format-version)
 676   (let* ((old-list (bookmark-alist-from-buffer))
 677          (new-list (bookmark-upgrade-version-0-alist old-list)))
 678     (delete-region (point-min) (point-max))
 679     (bookmark-insert-file-format-version-stamp)
 680     (pp new-list (current-buffer))
 681     (save-buffer))
 682   (goto-char (point-min))
 683   (message "Upgrading bookmark format from 0 to %d...done"
 684            bookmark-file-format-version)
 685   )
 686
 687
 688 (defun bookmark-grok-file-format-version ()
 689   "Return an integer which is the file-format version of this bookmark file.
 690 This expects to be called from `point-min' in a bookmark file."
 691   (if (looking-at "^;;;;")
 692       (save-excursion
 693         (save-match-data
 694           (re-search-forward "[0-9]")
 695           (forward-char -1)
 696           (read (current-buffer))))
 697     ;; Else this is format version 0, the original one, which didn't
 698     ;; even have version stamps.
 699     0))
 700
 701
 702 (defun bookmark-maybe-upgrade-file-format ()
 703   "Check the file-format version of this bookmark file.
 704 If the version is not up-to-date, upgrade it automatically.
 705 This expects to be called from `point-min' in a bookmark file."
 706   (let ((version (bookmark-grok-file-format-version)))
 707     (cond
 708      ((= version bookmark-file-format-version)
 709       ) ; home free -- version is current
 710      ((= version 0)
 711       (bookmark-upgrade-file-format-from-0))
 712      (t
 713       (error "Bookmark file format version strangeness")))))
 714
 715
 716 (defun bookmark-insert-file-format-version-stamp ()
 717   "Insert text indicating current version of bookmark file format."
 718   (insert
 719    (format ";;;; Emacs Bookmark Format Version %d ;;;;\n"
 720            bookmark-file-format-version))
 721   (insert ";;; This format is meant to be slightly human-readable;\n"
 722           ";;; nevertheless, you probably don't want to edit it.\n"
 723           ";;; "
 724           bookmark-end-of-version-stamp-marker))
 725
 726
 727 ;;; end file-format stuff
 728
 729 \f
 730 ;;; Generic helpers.
 731
 732 (defun bookmark-maybe-message (fmt &rest args)
 733   "Apply `message' to FMT and ARGS, but only if the display is fast enough."
 734   (if (>= baud-rate 9600)
 735       (apply 'message fmt args)))
 736
 737 \f
 738 ;;; Core code:
 739
 740 (defvar bookmark-minibuffer-read-name-map
 741   (let ((map (make-sparse-keymap)))
 742     (set-keymap-parent map minibuffer-local-map)
 743     (define-key map "\C-w" 'bookmark-yank-word)
 744     map))
 745
 746 ;;;###autoload
 747 (defun bookmark-set (&optional name no-overwrite)
 748   "Set a bookmark named NAME at the current location.
 749 If name is nil, then prompt the user.
 750
 751 With a prefix arg (non-nil NO-OVERWRITE), do not overwrite any
 752 existing bookmark that has the same name as NAME, but instead push the
 753 new bookmark onto the bookmark alist.  The most recently set bookmark
 754 with name NAME is thus the one in effect at any given time, but the
 755 others are still there, should the user decide to delete the most
 756 recent one.
 757
 758 To yank words from the text of the buffer and use them as part of the
 759 bookmark name, type C-w while setting a bookmark.  Successive C-w's
 760 yank successive words.
 761
 762 Typing C-u inserts (at the bookmark name prompt) the name of the last
 763 bookmark used in the document where the new bookmark is being set;
 764 this helps you use a single bookmark name to track progress through a
 765 large document.  If there is no prior bookmark for this document, then
 766 C-u inserts an appropriate name based on the buffer or file.
 767
 768 Use \\[bookmark-delete] to remove bookmarks (you give it a name and
 769 it removes only the first instance of a bookmark with that name from
 770 the list of bookmarks.)"
 771   (interactive (list nil current-prefix-arg))
 772   (unwind-protect
 773        (let* ((record (bookmark-make-record))
 774               ;; `defaults' is a transient element of the
 775               ;; extensible format described above in the section
 776               ;; `File format stuff'.  Bookmark record functions
 777               ;; can use it to specify a list of default values
 778               ;; accessible via M-n while reading a bookmark name.
 779               (defaults (bookmark-prop-get record 'defaults))
 780               (default (if (consp defaults) (car defaults) defaults)))
 781
 782          (if defaults
 783              ;; Don't store default values in the record.
 784              (setq record (assq-delete-all 'defaults record))
 785            ;; When no defaults in the record, use its first element.
 786            (setq defaults (car record) default defaults))
 787
 788          (bookmark-maybe-load-default-file)
 789          ;; Don't set `bookmark-yank-point' and `bookmark-current-buffer'
 790          ;; if they have been already set in another buffer. (e.g gnus-art).
 791          (unless (and bookmark-yank-point
 792                       bookmark-current-buffer)
 793            (setq bookmark-yank-point (point))
 794            (setq bookmark-current-buffer (current-buffer)))
 795
 796          (let ((str
 797                 (or name
 798                     (read-from-minibuffer
 799                      (format "Set bookmark (%s): " default)
 800                      nil
 801                      bookmark-minibuffer-read-name-map
 802                      nil nil defaults))))
 803            (and (string-equal str "") (setq str default))
 804            (bookmark-store str (cdr record) no-overwrite)
 805
 806            ;; Ask for an annotation buffer for this bookmark
 807            (when bookmark-use-annotations
 808              (bookmark-edit-annotation str))))
 809     (setq bookmark-yank-point nil)
 810     (setq bookmark-current-buffer nil)))
 811
 812
 813 (defun bookmark-kill-line (&optional newline-too)
 814   "Kill from point to end of line.
 815 If optional arg NEWLINE-TOO is non-nil, delete the newline too.
 816 Does not affect the kill ring."
 817   (let ((eol (line-end-position)))
 818     (delete-region (point) eol)
 819     (if (and newline-too (looking-at "\n"))
 820         (delete-char 1))))
 821
 822
 823 ;; Defvars to avoid compilation warnings:
 824 (defvar bookmark-annotation-name nil
 825   "Variable holding the name of the bookmark.
 826 This is used in `bookmark-edit-annotation' to record the bookmark
 827 whose annotation is being edited.")
 828
 829
 830 (defun bookmark-default-annotation-text (bookmark-name)
 831   "Return default annotation text for BOOKMARK-NAME.
 832 The default annotation text is simply some text explaining how to use
 833 annotations."
 834   (concat "#  Type the annotation for bookmark '" bookmark-name "' here.\n"
 835           "#  All lines which start with a '#' will be deleted.\n"
 836           "#  Type C-c C-c when done.\n#\n"
 837           "#  Author: " (user-full-name) " <" (user-login-name) "@"
 838           (system-name) ">\n"
 839           "#  Date:    " (current-time-string) "\n"))
 840
 841
 842 (define-obsolete-variable-alias 'bookmark-read-annotation-text-func
 843   'bookmark-edit-annotation-text-func "23.1")
 844 (defvar bookmark-edit-annotation-text-func 'bookmark-default-annotation-text
 845   "Function to return default text to use for a bookmark annotation.
 846 It takes one argument, the name of the bookmark, as a string.")
 847
 848 (defvar bookmark-edit-annotation-mode-map
 849   (let ((map (make-sparse-keymap)))
 850     (set-keymap-parent map text-mode-map)
 851     (define-key map "\C-c\C-c" 'bookmark-send-edited-annotation)
 852     map)
 853   "Keymap for editing an annotation of a bookmark.")
 854
 855
 856 (defun bookmark-edit-annotation-mode (bookmark-name-or-record)
 857   "Mode for editing the annotation of bookmark BOOKMARK-NAME-OR-RECORD.
 858 When you have finished composing, type \\[bookmark-send-annotation].
 859
 860 \\{bookmark-edit-annotation-mode-map}"
 861   (interactive)
 862   (kill-all-local-variables)
 863   (make-local-variable 'bookmark-annotation-name)
 864   (setq bookmark-annotation-name bookmark-name-or-record)
 865   (use-local-map bookmark-edit-annotation-mode-map)
 866   (setq major-mode 'bookmark-edit-annotation-mode
 867         mode-name "Edit Bookmark Annotation")
 868   (insert (funcall bookmark-edit-annotation-text-func bookmark-name-or-record))
 869   (let ((annotation (bookmark-get-annotation bookmark-name-or-record)))
 870     (if (and annotation (not (string-equal annotation "")))
 871         (insert annotation)))
 872   (run-mode-hooks 'text-mode-hook))
 873
 874
 875 (defun bookmark-send-edited-annotation ()
 876   "Use buffer contents as annotation for a bookmark.
 877 Lines beginning with `#' are ignored."
 878   (interactive)
 879   (if (not (eq major-mode 'bookmark-edit-annotation-mode))
 880       (error "Not in bookmark-edit-annotation-mode"))
 881   (goto-char (point-min))
 882   (while (< (point) (point-max))
 883     (if (looking-at "^#")
 884         (bookmark-kill-line t)
 885       (forward-line 1)))
 886   ;; Take no chances with text properties.
 887   (let ((annotation (buffer-substring-no-properties (point-min) (point-max)))
 888         (bookmark-name bookmark-annotation-name))
 889     (bookmark-set-annotation bookmark-name annotation)
 890     (setq bookmark-alist-modification-count
 891           (1+ bookmark-alist-modification-count))
 892     (bookmark-bmenu-surreptitiously-rebuild-list))
 893   (kill-buffer (current-buffer)))
 894
 895
 896 (defun bookmark-edit-annotation (bookmark-name-or-record)
 897   "Pop up a buffer for editing bookmark BOOKMARK-NAME-OR-RECORD's annotation."
 898   (pop-to-buffer (generate-new-buffer-name "*Bookmark Annotation Compose*"))
 899   (bookmark-edit-annotation-mode bookmark-name-or-record))
 900
 901
 902 (defun bookmark-buffer-name ()
 903   "Return the name of the current buffer in a form usable as a bookmark name.
 904 If the buffer is associated with a file or directory, use that name."
 905   (cond
 906    ;; Or are we a file?
 907    (buffer-file-name (file-name-nondirectory buffer-file-name))
 908    ;; Or are we a directory?
 909    ((and (boundp 'dired-directory) dired-directory)
 910     (let* ((dirname (if (stringp dired-directory)
 911                         dired-directory
 912                       (car dired-directory)))
 913            (idx (1- (length dirname))))
 914       ;; Strip the trailing slash.
 915       (if (= ?/ (aref dirname idx))
 916           (file-name-nondirectory (substring dirname 0 idx))
 917         ;; Else return the current-buffer
 918         (buffer-name (current-buffer)))))
 919    ;; If all else fails, use the buffer's name.
 920    (t
 921     (buffer-name (current-buffer)))))
 922
 923
 924 (defun bookmark-yank-word ()
 925   "Get the next word from buffer `bookmark-current-buffer' and append
 926 it to the name of the bookmark currently being set, advancing
 927 `bookmark-yank-point' by one word."
 928   (interactive)
 929   (let ((string (with-current-buffer bookmark-current-buffer
 930                   (goto-char bookmark-yank-point)
 931                   (buffer-substring-no-properties
 932                    (point)
 933                    (progn
 934                      (forward-word 1)
 935                      (setq bookmark-yank-point (point)))))))
 936     (insert string)))
 937
 938 (defun bookmark-buffer-file-name ()
 939   "Return the current buffer's file in a way useful for bookmarks."
 940   ;; Abbreviate the path, both so it's shorter and so it's more
 941   ;; portable.  E.g., the user's home dir might be a different
 942   ;; path on different machines, but "~/" will still reach it.
 943   (abbreviate-file-name
 944    (cond
 945     (buffer-file-name buffer-file-name)
 946     ((and (boundp 'dired-directory) dired-directory)
 947      (if (stringp dired-directory)
 948          dired-directory
 949        (car dired-directory)))
 950     (t (error "Buffer not visiting a file or directory")))))
 951
 952
 953 (defun bookmark-maybe-load-default-file ()
 954   "If bookmarks have not been loaded from the default place, load them."
 955   (and (not bookmarks-already-loaded)
 956        (null bookmark-alist)
 957        (prog2
 958            (and
 959             ;; Possibly the old bookmark file, "~/.emacs-bkmrks", needs
 960             ;; to be renamed.
 961             (file-exists-p bookmark-old-default-file)
 962             (not (file-exists-p bookmark-default-file))
 963             (rename-file bookmark-old-default-file
 964                          bookmark-default-file))
 965            ;; return t so the `and' will continue...
 966            t)
 967
 968        (file-readable-p bookmark-default-file)
 969        (bookmark-load bookmark-default-file t t)
 970        (setq bookmarks-already-loaded t)))
 971
 972
 973 (defun bookmark-maybe-sort-alist ()
 974   "Return `bookmark-alist' for display.
 975 If `bookmark-sort-flag' is non-nil, then return a sorted copy of the alist."
 976   (if bookmark-sort-flag
 977       (sort (copy-alist bookmark-alist)
 978             (function
 979              (lambda (x y) (string-lessp (car x) (car y)))))
 980     bookmark-alist))
 981
 982
 983 (defvar bookmark-after-jump-hook nil
 984   "Hook run after `bookmark-jump' jumps to a bookmark.
 985 Useful for example to unhide text in `outline-mode'.")
 986
 987 (defun bookmark--jump-via (bookmark-name-or-record display-function)
 988   "Handle BOOKMARK-NAME-OR-RECORD, then call DISPLAY-FUNCTION with
 989 current buffer as argument.
 990
 991 After calling DISPLAY-FUNCTION, set window point to the point specified
 992 by BOOKMARK-NAME-OR-RECORD, if necessary, run `bookmark-after-jump-hook',
 993 and then show any annotations for this bookmark."
 994   (bookmark-handle-bookmark bookmark-name-or-record)
 995   (save-current-buffer
 996     (funcall display-function (current-buffer)))
 997   (let ((win (get-buffer-window (current-buffer) 0)))
 998     (if win (set-window-point win (point))))
 999   ;; FIXME: we used to only run bookmark-after-jump-hook in
1000   ;; `bookmark-jump' itself, but in none of the other commands.
1001   (run-hooks 'bookmark-after-jump-hook)
1002   (if bookmark-automatically-show-annotations
1003       ;; if there is an annotation for this bookmark,
1004       ;; show it in a buffer.
1005       (bookmark-show-annotation bookmark-name-or-record)))
1006
1007
1008 ;;;###autoload
1009 (defun bookmark-jump (bookmark &optional display-func)
1010   "Jump to bookmark BOOKMARK (a point in some file).
1011 You may have a problem using this function if the value of variable
1012 `bookmark-alist' is nil.  If that happens, you need to load in some
1013 bookmarks.  See help on function `bookmark-load' for more about
1014 this.
1015
1016 If the file pointed to by BOOKMARK no longer exists, you will be asked
1017 if you wish to give the bookmark a new location, and `bookmark-jump'
1018 will then jump to the new location, as well as recording it in place
1019 of the old one in the permanent bookmark record.
1020
1021 BOOKMARK is usually a bookmark name (a string).  It can also be a
1022 bookmark record, but this is usually only done by programmatic callers.
1023
1024 If DISPLAY-FUNC is non-nil, it is a function to invoke to display the
1025 bookmark.  It defaults to `switch-to-buffer'.  A typical value for
1026 DISPLAY-FUNC would be `switch-to-buffer-other-window'."
1027   (interactive
1028    (list (bookmark-completing-read "Jump to bookmark"
1029                                    bookmark-current-bookmark)))
1030   (unless bookmark
1031     (error "No bookmark specified"))
1032   (bookmark-maybe-historicize-string bookmark)
1033   (bookmark--jump-via bookmark (or display-func 'switch-to-buffer)))
1034
1035
1036 ;;;###autoload
1037 (defun bookmark-jump-other-window (bookmark)
1038   "Jump to BOOKMARK in another window.  See `bookmark-jump' for more."
1039   (interactive
1040    (list (bookmark-completing-read "Jump to bookmark (in another window)"
1041                                    bookmark-current-bookmark)))
1042   (bookmark-jump bookmark 'switch-to-buffer-other-window))
1043
1044
1045 (defun bookmark-jump-noselect (bookmark)
1046   "Return the location pointed to by BOOKMARK (see `bookmark-jump').
1047 The return value has the form (BUFFER . POINT).
1048
1049 Note: this function is deprecated and is present for Emacs 22
1050 compatibility only."
1051   (declare (obsolete bookmark-handle-bookmark "23.1"))
1052   (save-excursion
1053     (bookmark-handle-bookmark bookmark)
1054     (cons (current-buffer) (point))))
1055
1056 (defun bookmark-handle-bookmark (bookmark-name-or-record)
1057   "Call BOOKMARK-NAME-OR-RECORD's handler or `bookmark-default-handler'
1058 if it has none.  This changes current buffer and point and returns nil,
1059 or signals a `file-error'.
1060
1061 If BOOKMARK-NAME-OR-RECORD has no file, this is a no-op.  If
1062 BOOKMARK-NAME-OR-RECORD has a file, but that file no longer exists,
1063 then offer interactively to relocate BOOKMARK-NAME-OR-RECORD."
1064   (condition-case err
1065       (funcall (or (bookmark-get-handler bookmark-name-or-record)
1066                    'bookmark-default-handler)
1067                (bookmark-get-bookmark bookmark-name-or-record))
1068     (bookmark-error-no-filename         ;file-error
1069      ;; We were unable to find the marked file, so ask if user wants to
1070      ;; relocate the bookmark, else remind them to consider deletion.
1071      (when (stringp bookmark-name-or-record)
1072        ;; `bookmark-name-or-record' can be either a bookmark name
1073        ;; (from `bookmark-alist')  or a bookmark object.  If it's an
1074        ;; object, we assume it's a bookmark used internally by some
1075        ;; other package.
1076        (let ((file (bookmark-get-filename bookmark-name-or-record)))
1077          (when file        ;Don't know how to relocate if there's no `file'.
1078            ;; If file is not a dir, directory-file-name just returns file.
1079            (let ((display-name (directory-file-name file)))
1080              (ding)
1081              ;; Dialog boxes can accept a file target, but usually don't
1082              ;; know how to accept a directory target (at least, this
1083              ;; is true in Gnome on GNU/Linux, and Bug#4230 says it's
1084              ;; true on Windows as well).  So we suppress file dialogs
1085              ;; when relocating.
1086              (let ((use-dialog-box nil)
1087                    (use-file-dialog nil))
1088                (if (y-or-n-p (concat display-name " nonexistent.  Relocate \""
1089                                      bookmark-name-or-record "\"? "))
1090                    (progn
1091                      (bookmark-relocate bookmark-name-or-record)
1092                      ;; Try again.
1093                      (funcall (or (bookmark-get-handler bookmark-name-or-record)
1094                                   'bookmark-default-handler)
1095                               (bookmark-get-bookmark bookmark-name-or-record)))
1096                  (message
1097                   "Bookmark not relocated; consider removing it (%s)."
1098                   bookmark-name-or-record)
1099                  (signal (car err) (cdr err))))))))))
1100   ;; Added by db.
1101   (when (stringp bookmark-name-or-record)
1102     (setq bookmark-current-bookmark bookmark-name-or-record))
1103   nil)
1104
1105 (put 'bookmark-error-no-filename
1106      'error-conditions
1107      '(error bookmark-errors bookmark-error-no-filename))
1108 (put 'bookmark-error-no-filename
1109      'error-message
1110      "Bookmark has no associated file (or directory)")
1111
1112 (defun bookmark-default-handler (bmk-record)
1113   "Default handler to jump to a particular bookmark location.
1114 BMK-RECORD is a bookmark record, not a bookmark name (i.e., not a string).
1115 Changes current buffer and point and returns nil, or signals a `file-error'."
1116   (let ((file          (bookmark-get-filename bmk-record))
1117         (buf           (bookmark-prop-get bmk-record 'buffer))
1118         (forward-str   (bookmark-get-front-context-string bmk-record))
1119         (behind-str    (bookmark-get-rear-context-string bmk-record))
1120         (place         (bookmark-get-position bmk-record)))
1121     (set-buffer
1122      (cond
1123       ((and file (file-readable-p file) (not (buffer-live-p buf)))
1124        (find-file-noselect file))
1125       ;; No file found.  See if buffer BUF have been created.
1126       ((and buf (get-buffer buf)))
1127       (t ;; If not, raise error.
1128        (signal 'bookmark-error-no-filename (list 'stringp file)))))
1129     (if place (goto-char place))
1130     ;; Go searching forward first.  Then, if forward-str exists and
1131     ;; was found in the file, we can search backward for behind-str.
1132     ;; Rationale is that if text was inserted between the two in the
1133     ;; file, it's better to be put before it so you can read it,
1134     ;; rather than after and remain perhaps unaware of the changes.
1135     (when (and forward-str (search-forward forward-str (point-max) t))
1136       (goto-char (match-beginning 0)))
1137     (when (and behind-str (search-backward behind-str (point-min) t))
1138       (goto-char (match-end 0)))
1139     nil))
1140
1141 ;;;###autoload
1142 (defun bookmark-relocate (bookmark-name)
1143   "Relocate BOOKMARK-NAME to another file, reading file name with minibuffer.
1144
1145 This makes an already existing bookmark point to that file, instead of
1146 the one it used to point at.  Useful when a file has been renamed
1147 after a bookmark was set in it."
1148   (interactive (list (bookmark-completing-read "Bookmark to relocate")))
1149   (bookmark-maybe-historicize-string bookmark-name)
1150   (bookmark-maybe-load-default-file)
1151   (let* ((bmrk-filename (bookmark-get-filename bookmark-name))
1152          (newloc (abbreviate-file-name
1153                   (expand-file-name
1154                    (read-file-name
1155                     (format "Relocate %s to: " bookmark-name)
1156                     (file-name-directory bmrk-filename))))))
1157     (bookmark-set-filename bookmark-name newloc)
1158     (setq bookmark-alist-modification-count
1159           (1+ bookmark-alist-modification-count))
1160     (if (bookmark-time-to-save-p)
1161         (bookmark-save))
1162     (bookmark-bmenu-surreptitiously-rebuild-list)))
1163
1164
1165 ;;;###autoload
1166 (defun bookmark-insert-location (bookmark-name &optional no-history)
1167   "Insert the name of the file associated with BOOKMARK-NAME.
1168
1169 Optional second arg NO-HISTORY means don't record this in the
1170 minibuffer history list `bookmark-history'."
1171   (interactive (list (bookmark-completing-read "Insert bookmark location")))
1172   (or no-history (bookmark-maybe-historicize-string bookmark-name))
1173   (let ((start (point)))
1174     (prog1
1175         (insert (bookmark-location bookmark-name))
1176       (if (display-mouse-p)
1177           (add-text-properties
1178            start
1179            (save-excursion (re-search-backward
1180                             "[^ \t]")
1181                            (1+ (point)))
1182            '(mouse-face highlight
1183              follow-link t
1184              help-echo "mouse-2: go to this bookmark in other window"))))))
1185
1186 ;;;###autoload
1187 (defalias 'bookmark-locate 'bookmark-insert-location)
1188
1189 (defun bookmark-location (bookmark-name-or-record)
1190   "Return a description of the location of BOOKMARK-NAME-OR-RECORD."
1191   (bookmark-maybe-load-default-file)
1192   ;; We could call the `handler' and ask for it to construct a description
1193   ;; dynamically: it would open up several new possibilities, but it
1194   ;; would have the major disadvantage of forcing to load each and
1195   ;; every handler when the user calls bookmark-menu.
1196   (or (bookmark-prop-get bookmark-name-or-record 'location)
1197       (bookmark-get-filename bookmark-name-or-record)
1198       "-- Unknown location --"))
1199
1200
1201 ;;;###autoload
1202 (defun bookmark-rename (old-name &optional new-name)
1203   "Change the name of OLD-NAME bookmark to NEW-NAME name.
1204 If called from keyboard, prompt for OLD-NAME and NEW-NAME.
1205 If called from menubar, select OLD-NAME from a menu and prompt for NEW-NAME.
1206
1207 If called from Lisp, prompt for NEW-NAME if only OLD-NAME was passed
1208 as an argument.  If called with two strings, then no prompting is done.
1209 You must pass at least OLD-NAME when calling from Lisp.
1210
1211 While you are entering the new name, consecutive C-w's insert
1212 consecutive words from the text of the buffer into the new bookmark
1213 name."
1214   (interactive (list (bookmark-completing-read "Old bookmark name")))
1215   (bookmark-maybe-historicize-string old-name)
1216   (bookmark-maybe-load-default-file)
1217
1218   (setq bookmark-yank-point (point))
1219   (setq bookmark-current-buffer (current-buffer))
1220   (let ((final-new-name
1221          (or new-name   ; use second arg, if non-nil
1222              (read-from-minibuffer
1223               "New name: "
1224               nil
1225               (let ((now-map (copy-keymap minibuffer-local-map)))
1226                 (define-key now-map "\C-w" 'bookmark-yank-word)
1227                 now-map)
1228               nil
1229               'bookmark-history))))
1230     (bookmark-set-name old-name final-new-name)
1231     (setq bookmark-current-bookmark final-new-name)
1232     (bookmark-bmenu-surreptitiously-rebuild-list)
1233     (setq bookmark-alist-modification-count
1234           (1+ bookmark-alist-modification-count))
1235     (if (bookmark-time-to-save-p)
1236         (bookmark-save))))
1237
1238
1239 ;;;###autoload
1240 (defun bookmark-insert (bookmark-name)
1241   "Insert the text of the file pointed to by bookmark BOOKMARK-NAME.
1242 BOOKMARK-NAME is a bookmark name (a string), not a bookmark record.
1243
1244 You may have a problem using this function if the value of variable
1245 `bookmark-alist' is nil.  If that happens, you need to load in some
1246 bookmarks.  See help on function `bookmark-load' for more about
1247 this."
1248   (interactive (list (bookmark-completing-read "Insert bookmark contents")))
1249   (bookmark-maybe-historicize-string bookmark-name)
1250   (bookmark-maybe-load-default-file)
1251   (let ((orig-point (point))
1252         (str-to-insert
1253          (save-current-buffer
1254            (bookmark-handle-bookmark bookmark-name)
1255            (buffer-string))))
1256     (insert str-to-insert)
1257     (push-mark)
1258     (goto-char orig-point)))
1259
1260
1261 ;;;###autoload
1262 (defun bookmark-delete (bookmark-name &optional batch)
1263   "Delete BOOKMARK-NAME from the bookmark list.
1264
1265 Removes only the first instance of a bookmark with that name.  If
1266 there are one or more other bookmarks with the same name, they will
1267 not be deleted.  Defaults to the \"current\" bookmark (that is, the
1268 one most recently used in this file, if any).
1269 Optional second arg BATCH means don't update the bookmark list buffer,
1270 probably because we were called from there."
1271   (interactive
1272    (list (bookmark-completing-read "Delete bookmark"
1273                                    bookmark-current-bookmark)))
1274   (bookmark-maybe-historicize-string bookmark-name)
1275   (bookmark-maybe-load-default-file)
1276   (let ((will-go (bookmark-get-bookmark bookmark-name 'noerror)))
1277     (setq bookmark-alist (delq will-go bookmark-alist))
1278     ;; Added by db, nil bookmark-current-bookmark if the last
1279     ;; occurrence has been deleted
1280     (or (bookmark-get-bookmark bookmark-current-bookmark 'noerror)
1281         (setq bookmark-current-bookmark nil)))
1282   (unless batch
1283     (bookmark-bmenu-surreptitiously-rebuild-list))
1284   (setq bookmark-alist-modification-count
1285         (1+ bookmark-alist-modification-count))
1286   (when (bookmark-time-to-save-p)
1287     (bookmark-save)))
1288
1289
1290 (defun bookmark-time-to-save-p (&optional final-time)
1291   "Return t if it is time to save bookmarks to disk, nil otherwise.
1292 Optional argument FINAL-TIME means this is being called when Emacs
1293 is being killed, so save even if `bookmark-save-flag' is a number and
1294 is greater than `bookmark-alist-modification-count'."
1295   ;; By Gregory M. Saunders <saunders{_AT_}cis.ohio-state.edu>
1296   (cond (final-time
1297          (and (> bookmark-alist-modification-count 0)
1298               bookmark-save-flag))
1299         ((numberp bookmark-save-flag)
1300          (>= bookmark-alist-modification-count bookmark-save-flag))
1301         (t
1302          nil)))
1303
1304
1305 ;;;###autoload
1306 (defun bookmark-write ()
1307   "Write bookmarks to a file (reading the file name with the minibuffer).
1308 Don't use this in Lisp programs; use `bookmark-save' instead."
1309   (interactive)
1310   (bookmark-maybe-load-default-file)
1311   (bookmark-save t))
1312
1313
1314 ;;;###autoload
1315 (defun bookmark-save (&optional parg file)
1316   "Save currently defined bookmarks.
1317 Saves by default in the file defined by the variable
1318 `bookmark-default-file'.  With a prefix arg, save it in file FILE
1319 \(second argument).
1320
1321 If you are calling this from Lisp, the two arguments are PARG and
1322 FILE, and if you just want it to write to the default file, then
1323 pass no arguments.  Or pass in nil and FILE, and it will save in FILE
1324 instead.  If you pass in one argument, and it is non-nil, then the
1325 user will be interactively queried for a file to save in.
1326
1327 When you want to load in the bookmarks from a file, use
1328 `bookmark-load', \\[bookmark-load].  That function will prompt you
1329 for a file, defaulting to the file defined by variable
1330 `bookmark-default-file'."
1331   (interactive "P")
1332   (bookmark-maybe-load-default-file)
1333   (cond
1334    ((and (null parg) (null file))
1335     ;;whether interactive or not, write to default file
1336     (bookmark-write-file bookmark-default-file))
1337    ((and (null parg) file)
1338     ;;whether interactive or not, write to given file
1339     (bookmark-write-file file))
1340    ((and parg (not file))
1341     ;;have been called interactively w/ prefix arg
1342     (let ((file (read-file-name "File to save bookmarks in: ")))
1343       (bookmark-write-file file)))
1344    (t ; someone called us with prefix-arg *and* a file, so just write to file
1345     (bookmark-write-file file)))
1346   ;; signal that we have synced the bookmark file by setting this to
1347   ;; 0.  If there was an error at any point before, it will not get
1348   ;; set, which is what we want.
1349   (setq bookmark-alist-modification-count 0))
1350
1351
1352 \f
1353 (defun bookmark-write-file (file)
1354   "Write `bookmark-alist' to FILE."
1355   (bookmark-maybe-message "Saving bookmarks to file %s..." file)
1356   (with-current-buffer (get-buffer-create " *Bookmarks*")
1357     (goto-char (point-min))
1358     (delete-region (point-min) (point-max))
1359     (let ((print-length nil)
1360           (print-level nil))
1361       (bookmark-insert-file-format-version-stamp)
1362       (insert "(")
1363       ;; Rather than a single call to `pp' we make one per bookmark.
1364       ;; Apparently `pp' has a poor algorithmic complexity, so this
1365       ;; scales a lot better.  bug#4485.
1366       (dolist (i bookmark-alist) (pp i (current-buffer)))
1367       (insert ")")
1368       (let ((version-control
1369              (cond
1370               ((null bookmark-version-control) nil)
1371               ((eq 'never bookmark-version-control) 'never)
1372               ((eq 'nospecial bookmark-version-control) version-control)
1373               (t t))))
1374         (condition-case nil
1375             (write-region (point-min) (point-max) file)
1376           (file-error (message "Can't write %s" file)))
1377         (kill-buffer (current-buffer))
1378         (bookmark-maybe-message
1379          "Saving bookmarks to file %s...done" file)))))
1380
1381
1382 (defun bookmark-import-new-list (new-list)
1383   "Add NEW-LIST of bookmarks to `bookmark-alist'.
1384 Rename new bookmarks as needed using suffix \"<N>\" (N=1,2,3...), when
1385 they conflict with existing bookmark names."
1386   (let ((names (bookmark-all-names)))
1387     (dolist (full-record new-list)
1388       (bookmark-maybe-rename full-record names)
1389       (setq bookmark-alist (nconc bookmark-alist (list full-record)))
1390       (push (bookmark-name-from-full-record full-record) names))))
1391
1392
1393 (defun bookmark-maybe-rename (full-record names)
1394   "Rename bookmark FULL-RECORD if its current name is already used.
1395 This is a helper for `bookmark-import-new-list'."
1396   (let ((found-name (bookmark-name-from-full-record full-record)))
1397     (if (member found-name names)
1398         ;; We've got a conflict, so generate a new name
1399         (let ((count 2)
1400               (new-name found-name))
1401           (while (member new-name names)
1402             (setq new-name (concat found-name (format "<%d>" count)))
1403             (setq count (1+ count)))
1404           (bookmark-set-name full-record new-name)))))
1405
1406
1407 ;;;###autoload
1408 (defun bookmark-load (file &optional overwrite no-msg)
1409   "Load bookmarks from FILE (which must be in bookmark format).
1410 Appends loaded bookmarks to the front of the list of bookmarks.  If
1411 optional second argument OVERWRITE is non-nil, existing bookmarks are
1412 destroyed.  Optional third arg NO-MSG means don't display any messages
1413 while loading.
1414
1415 If you load a file that doesn't contain a proper bookmark alist, you
1416 will corrupt Emacs's bookmark list.  Generally, you should only load
1417 in files that were created with the bookmark functions in the first
1418 place.  Your own personal bookmark file, `~/.emacs.bmk', is
1419 maintained automatically by Emacs; you shouldn't need to load it
1420 explicitly.
1421
1422 If you load a file containing bookmarks with the same names as
1423 bookmarks already present in your Emacs, the new bookmarks will get
1424 unique numeric suffixes \"<2>\", \"<3>\", ... following the same
1425 method buffers use to resolve name collisions."
1426   (interactive
1427    (list (read-file-name
1428           (format "Load bookmarks from: (%s) "
1429                   bookmark-default-file)
1430           ;;Default might not be used often,
1431           ;;but there's no better default, and
1432           ;;I guess it's better than none at all.
1433           "~/" bookmark-default-file 'confirm)))
1434   (setq file (abbreviate-file-name (expand-file-name file)))
1435   (if (not (file-readable-p file))
1436       (error "Cannot read bookmark file %s" file)
1437     (if (null no-msg)
1438         (bookmark-maybe-message "Loading bookmarks from %s..." file))
1439     (with-current-buffer (let ((enable-local-variables nil))
1440                            (find-file-noselect file))
1441       (goto-char (point-min))
1442       (bookmark-maybe-upgrade-file-format)
1443       (let ((blist (bookmark-alist-from-buffer)))
1444         (if (listp blist)
1445             (progn
1446               (if overwrite
1447                   (progn
1448                     (setq bookmark-alist blist)
1449                     (setq bookmark-alist-modification-count 0))
1450                 ;; else
1451                 (bookmark-import-new-list blist)
1452                 (setq bookmark-alist-modification-count
1453                       (1+ bookmark-alist-modification-count)))
1454               (if (string-equal
1455                    (abbreviate-file-name
1456                     (expand-file-name bookmark-default-file))
1457                    file)
1458                   (setq bookmarks-already-loaded t))
1459               (bookmark-bmenu-surreptitiously-rebuild-list))
1460           (error "Invalid bookmark list in %s" file)))
1461       (kill-buffer (current-buffer)))
1462     (if (null no-msg)
1463         (bookmark-maybe-message "Loading bookmarks from %s...done" file))))
1464
1465
1466 \f
1467 ;;; Code supporting the dired-like bookmark menu.
1468 ;; Prefix is "bookmark-bmenu" for "buffer-menu":
1469
1470
1471 (defvar bookmark-bmenu-hidden-bookmarks ())
1472
1473
1474 (defvar bookmark-bmenu-mode-map
1475   (let ((map (make-keymap)))
1476     (set-keymap-parent map special-mode-map)
1477     (define-key map "v" 'bookmark-bmenu-select)
1478     (define-key map "w" 'bookmark-bmenu-locate)
1479     (define-key map "2" 'bookmark-bmenu-2-window)
1480     (define-key map "1" 'bookmark-bmenu-1-window)
1481     (define-key map "j" 'bookmark-bmenu-this-window)
1482     (define-key map "\C-c\C-c" 'bookmark-bmenu-this-window)
1483     (define-key map "f" 'bookmark-bmenu-this-window)
1484     (define-key map "\C-m" 'bookmark-bmenu-this-window)
1485     (define-key map "o" 'bookmark-bmenu-other-window)
1486     (define-key map "\C-o" 'bookmark-bmenu-switch-other-window)
1487     (define-key map "s" 'bookmark-bmenu-save)
1488     (define-key map "k" 'bookmark-bmenu-delete)
1489     (define-key map "\C-d" 'bookmark-bmenu-delete-backwards)
1490     (define-key map "x" 'bookmark-bmenu-execute-deletions)
1491     (define-key map "d" 'bookmark-bmenu-delete)
1492     (define-key map " " 'next-line)
1493     (define-key map "n" 'next-line)
1494     (define-key map "p" 'previous-line)
1495     (define-key map "\177" 'bookmark-bmenu-backup-unmark)
1496     (define-key map "u" 'bookmark-bmenu-unmark)
1497     (define-key map "m" 'bookmark-bmenu-mark)
1498     (define-key map "l" 'bookmark-bmenu-load)
1499     (define-key map "r" 'bookmark-bmenu-rename)
1500     (define-key map "R" 'bookmark-bmenu-relocate)
1501     (define-key map "t" 'bookmark-bmenu-toggle-filenames)
1502     (define-key map "a" 'bookmark-bmenu-show-annotation)
1503     (define-key map "A" 'bookmark-bmenu-show-all-annotations)
1504     (define-key map "e" 'bookmark-bmenu-edit-annotation)
1505     (define-key map "/" 'bookmark-bmenu-search)
1506     (define-key map [mouse-2] 'bookmark-bmenu-other-window-with-mouse)
1507     map))
1508
1509 ;; Bookmark Buffer Menu mode is suitable only for specially formatted
1510 ;; data.
1511 (put 'bookmark-bmenu-mode 'mode-class 'special)
1512
1513
1514 ;; todo: need to display whether or not bookmark exists as a buffer in
1515 ;; flag column.
1516
1517 ;; Format:
1518 ;; FLAGS  BOOKMARK [ LOCATION ]
1519
1520
1521 (defun bookmark-bmenu-surreptitiously-rebuild-list ()
1522   "Rebuild the Bookmark List if it exists.
1523 Don't affect the buffer ring order."
1524   (if (get-buffer "*Bookmark List*")
1525       (save-excursion
1526         (save-window-excursion
1527           (bookmark-bmenu-list)))))
1528
1529
1530 ;;;###autoload
1531 (defun bookmark-bmenu-list ()
1532   "Display a list of existing bookmarks.
1533 The list is displayed in a buffer named `*Bookmark List*'.
1534 The leftmost column displays a D if the bookmark is flagged for
1535 deletion, or > if it is flagged for displaying."
1536   (interactive)
1537   (bookmark-maybe-load-default-file)
1538   (let ((buf (get-buffer-create "*Bookmark List*")))
1539     (if (called-interactively-p 'interactive)
1540         (switch-to-buffer buf)
1541       (set-buffer buf)))
1542   (let ((inhibit-read-only t))
1543     (erase-buffer)
1544     (insert "% Bookmark\n- --------\n")
1545     (add-text-properties (point-min) (point)
1546                          '(font-lock-face bookmark-menu-heading))
1547     (dolist (full-record (bookmark-maybe-sort-alist))
1548       (let ((name        (bookmark-name-from-full-record full-record))
1549             (annotation  (bookmark-get-annotation full-record))
1550             (start       (point))
1551             end)
1552         ;; if a bookmark has an annotation, prepend a "*"
1553         ;; in the list of bookmarks.
1554         (insert (if (and annotation (not (string-equal annotation "")))
1555                     " *" "  ")
1556                 name)
1557         (setq end (point))
1558         (put-text-property
1559          (+ bookmark-bmenu-marks-width start) end 'bookmark-name-prop name)
1560         (when (display-mouse-p)
1561           (add-text-properties
1562            (+ bookmark-bmenu-marks-width start) end
1563            '(mouse-face highlight
1564              follow-link t
1565              help-echo "mouse-2: go to this bookmark in other window")))
1566         (insert "\n")))
1567     (set-buffer-modified-p (not (= bookmark-alist-modification-count 0)))
1568     (goto-char (point-min))
1569     (forward-line 2)
1570     (bookmark-bmenu-mode)
1571     (if bookmark-bmenu-toggle-filenames
1572         (bookmark-bmenu-toggle-filenames t))))
1573
1574 ;;;###autoload
1575 (defalias 'list-bookmarks 'bookmark-bmenu-list)
1576 ;;;###autoload
1577 (defalias 'edit-bookmarks 'bookmark-bmenu-list)
1578
1579
1580
1581 (define-derived-mode bookmark-bmenu-mode special-mode "Bookmark Menu"
1582   "Major mode for editing a list of bookmarks.
1583 Each line describes one of the bookmarks in Emacs.
1584 Letters do not insert themselves; instead, they are commands.
1585 Bookmark names preceded by a \"*\" have annotations.
1586 \\<bookmark-bmenu-mode-map>
1587 \\[bookmark-bmenu-mark] -- mark bookmark to be displayed.
1588 \\[bookmark-bmenu-select] -- select bookmark of line point is on.
1589   Also show bookmarks marked using m in other windows.
1590 \\[bookmark-bmenu-toggle-filenames] -- toggle displaying of filenames (they may obscure long bookmark names).
1591 \\[bookmark-bmenu-locate] -- display (in minibuffer) location of this bookmark.
1592 \\[bookmark-bmenu-1-window] -- select this bookmark in full-frame window.
1593 \\[bookmark-bmenu-2-window] -- select this bookmark in one window,
1594   together with bookmark selected before this one in another window.
1595 \\[bookmark-bmenu-this-window] -- select this bookmark in place of the bookmark menu buffer.
1596 \\[bookmark-bmenu-other-window] -- select this bookmark in another window,
1597   so the bookmark menu bookmark remains visible in its window.
1598 \\[bookmark-bmenu-switch-other-window] -- switch the other window to this bookmark.
1599 \\[bookmark-bmenu-rename] -- rename this bookmark (prompts for new name).
1600 \\[bookmark-bmenu-relocate] -- relocate this bookmark's file (prompts for new file).
1601 \\[bookmark-bmenu-delete] -- mark this bookmark to be deleted, and move down.
1602 \\[bookmark-bmenu-delete-backwards] -- mark this bookmark to be deleted, and move up.
1603 \\[bookmark-bmenu-execute-deletions] -- delete bookmarks marked with `\\[bookmark-bmenu-delete]'.
1604 \\[bookmark-bmenu-save] -- save the current bookmark list in the default file.
1605   With a prefix arg, prompts for a file to save in.
1606 \\[bookmark-bmenu-load] -- load in a file of bookmarks (prompts for file.)
1607 \\[bookmark-bmenu-unmark] -- remove all kinds of marks from current line.
1608   With prefix argument, also move up one line.
1609 \\[bookmark-bmenu-backup-unmark] -- back up a line and remove marks.
1610 \\[bookmark-bmenu-show-annotation] -- show the annotation, if it exists, for the current bookmark
1611   in another buffer.
1612 \\[bookmark-bmenu-show-all-annotations] -- show the annotations of all bookmarks in another buffer.
1613 \\[bookmark-bmenu-edit-annotation] -- edit the annotation for the current bookmark."
1614   (setq truncate-lines t)
1615   (setq buffer-read-only t))
1616
1617
1618 (defun bookmark-bmenu-toggle-filenames (&optional show)
1619   "Toggle whether filenames are shown in the bookmark list.
1620 Optional argument SHOW means show them unconditionally."
1621   (interactive)
1622   (cond
1623    (show
1624     (setq bookmark-bmenu-toggle-filenames nil)
1625     (bookmark-bmenu-show-filenames)
1626     (setq bookmark-bmenu-toggle-filenames t))
1627    (bookmark-bmenu-toggle-filenames
1628     (bookmark-bmenu-hide-filenames)
1629     (setq bookmark-bmenu-toggle-filenames nil))
1630    (t
1631     (bookmark-bmenu-show-filenames)
1632     (setq bookmark-bmenu-toggle-filenames t))))
1633
1634
1635 (defun bookmark-bmenu-show-filenames (&optional force)
1636   "In an interactive bookmark list, show filenames along with bookmarks.
1637 Non-nil FORCE forces a redisplay showing the filenames.  FORCE is used
1638 mainly for debugging, and should not be necessary in normal use."
1639   (if (and (not force) bookmark-bmenu-toggle-filenames)
1640       nil ;already shown, so do nothing
1641     (with-buffer-modified-unmodified
1642      (save-excursion
1643        (save-window-excursion
1644          (goto-char (point-min))
1645          (forward-line 2)
1646          (setq bookmark-bmenu-hidden-bookmarks ())
1647          (let ((inhibit-read-only t))
1648            (while (< (point) (point-max))
1649              (let ((bmrk (bookmark-bmenu-bookmark)))
1650                (push bmrk bookmark-bmenu-hidden-bookmarks)
1651                (let ((start (line-end-position)))
1652                  (move-to-column bookmark-bmenu-file-column t)
1653                  ;; Strip off `mouse-face' from the white spaces region.
1654                  (if (display-mouse-p)
1655                      (remove-text-properties start (point)
1656                                              '(mouse-face nil help-echo nil))))
1657                (delete-region (point) (progn (end-of-line) (point)))
1658                (insert "  ")
1659                ;; Pass the NO-HISTORY arg:
1660                (bookmark-insert-location bmrk t)
1661                (forward-line 1)))))))))
1662
1663
1664 (defun bookmark-bmenu-hide-filenames (&optional force)
1665   "In an interactive bookmark list, hide the filenames of the bookmarks.
1666 Non-nil FORCE forces a redisplay showing the filenames.  FORCE is used
1667 mainly for debugging, and should not be necessary in normal use."
1668   (when (and (not force) bookmark-bmenu-toggle-filenames)
1669     ;; nothing to hide if above is nil
1670     (with-buffer-modified-unmodified
1671      (save-excursion
1672        (goto-char (point-min))
1673        (forward-line 2)
1674        (setq bookmark-bmenu-hidden-bookmarks
1675              (nreverse bookmark-bmenu-hidden-bookmarks))
1676        (let ((inhibit-read-only t))
1677          (while bookmark-bmenu-hidden-bookmarks
1678            (move-to-column bookmark-bmenu-marks-width t)
1679            (bookmark-kill-line)
1680            (let ((name  (pop bookmark-bmenu-hidden-bookmarks))
1681                  (start (point)))
1682              (insert name)
1683              (put-text-property start (point) 'bookmark-name-prop name)
1684              (if (display-mouse-p)
1685                  (add-text-properties
1686                   start (point)
1687                   '(mouse-face
1688                     highlight follow-link t help-echo
1689                     "mouse-2: go to this bookmark in other window"))))
1690            (forward-line 1)))))))
1691
1692
1693 (defun bookmark-bmenu-ensure-position ()
1694   "If point is not on a bookmark line, move it to one.
1695 If before the first bookmark line, move to the first; if after the
1696 last full line, move to the last full line.  The return value is undefined."
1697   (cond ((< (count-lines (point-min) (point)) bookmark-bmenu-header-height)
1698          (goto-char (point-min))
1699          (forward-line bookmark-bmenu-header-height))
1700         ((and (bolp) (eobp))
1701          (beginning-of-line 0))))
1702
1703
1704 (defun bookmark-bmenu-bookmark ()
1705   "Return the bookmark for this line in an interactive bookmark list buffer."
1706   (bookmark-bmenu-ensure-position)
1707   (save-excursion
1708     (beginning-of-line)
1709     (forward-char bookmark-bmenu-marks-width)
1710     (get-text-property (point) 'bookmark-name-prop)))
1711
1712
1713 (defun bookmark-show-annotation (bookmark-name-or-record)
1714   "Display the annotation for BOOKMARK-NAME-OR-RECORD in a buffer,
1715 if an annotation exists."
1716   (let ((annotation (bookmark-get-annotation bookmark-name-or-record)))
1717     (when (and annotation (not (string-equal annotation "")))
1718       (save-excursion
1719         (let ((old-buf (current-buffer)))
1720           (pop-to-buffer (get-buffer-create "*Bookmark Annotation*") t)
1721           (delete-region (point-min) (point-max))
1722           (insert annotation)
1723           (goto-char (point-min))
1724           (switch-to-buffer-other-window old-buf))))))
1725
1726
1727 (defun bookmark-show-all-annotations ()
1728   "Display the annotations for all bookmarks in a buffer."
1729   (save-selected-window
1730     (pop-to-buffer (get-buffer-create "*Bookmark Annotation*") t)
1731     (delete-region (point-min) (point-max))
1732     (dolist (full-record bookmark-alist)
1733       (let* ((name (bookmark-name-from-full-record full-record))
1734              (ann  (bookmark-get-annotation full-record)))
1735         (insert (concat name ":\n"))
1736         (if (and ann (not (string-equal ann "")))
1737             ;; insert the annotation, indented by 4 spaces.
1738             (progn
1739               (save-excursion (insert ann) (unless (bolp)
1740                                              (insert "\n")))
1741               (while (< (point) (point-max))
1742                 (beginning-of-line)     ; paranoia
1743                 (insert "    ")
1744                 (forward-line)
1745                 (end-of-line))))))
1746     (goto-char (point-min))))
1747
1748
1749 (defun bookmark-bmenu-mark ()
1750   "Mark bookmark on this line to be displayed by \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-select]."
1751   (interactive)
1752   (beginning-of-line)
1753   (bookmark-bmenu-ensure-position)
1754   (with-buffer-modified-unmodified
1755    (let ((inhibit-read-only t))
1756      (delete-char 1)
1757      (insert ?>)
1758      (forward-line 1)
1759      (bookmark-bmenu-ensure-position))))
1760
1761
1762 (defun bookmark-bmenu-select ()
1763   "Select this line's bookmark; also display bookmarks marked with `>'.
1764 You can mark bookmarks with the \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-mark] command."
1765   (interactive)
1766   (let ((bmrk (bookmark-bmenu-bookmark))
1767         (menu (current-buffer))
1768         (others ())
1769         tem)
1770     (goto-char (point-min))
1771     (while (re-search-forward "^>" nil t)
1772       (setq tem (bookmark-bmenu-bookmark))
1773       (let ((inhibit-read-only t))
1774         (delete-char -1)
1775         (insert ?\s))
1776       (or (string-equal tem bmrk)
1777           (member tem others)
1778           (setq others (cons tem others))))
1779     (setq others (nreverse others)
1780           tem (/ (1- (frame-height)) (1+ (length others))))
1781     (delete-other-windows)
1782     (bookmark-jump bmrk)
1783     (bury-buffer menu)
1784     (if others
1785         (while others
1786           (split-window nil tem)
1787           (other-window 1)
1788           (bookmark-jump (car others))
1789           (setq others (cdr others)))
1790       (other-window 1))))
1791
1792
1793 (defun bookmark-bmenu-any-marks ()
1794   "Return non-nil if any bookmarks are marked in the marks column."
1795   (save-excursion
1796     (goto-char (point-min))
1797     (bookmark-bmenu-ensure-position)
1798     (catch 'found-mark
1799       (while (not (eobp))
1800         (beginning-of-line)
1801         (if (looking-at "^\\S-")
1802             (throw 'found-mark t)
1803           (forward-line 1)))
1804       nil)))
1805
1806
1807 (defun bookmark-bmenu-save (parg)
1808   "Save the current list into a bookmark file.
1809 With a prefix arg, prompts for a file to save them in."
1810   (interactive "P")
1811   (save-excursion
1812     (save-window-excursion
1813       (bookmark-save parg)
1814       (set-buffer-modified-p nil))))
1815
1816
1817 (defun bookmark-bmenu-load ()
1818   "Load the bookmark file and rebuild the bookmark menu-buffer."
1819   (interactive)
1820   (bookmark-bmenu-ensure-position)
1821   (save-excursion
1822     (save-window-excursion
1823       ;; This will call `bookmark-bmenu-list'
1824       (call-interactively 'bookmark-load))))
1825
1826
1827 (defun bookmark-bmenu-1-window ()
1828   "Select this line's bookmark, alone, in full frame."
1829   (interactive)
1830   (bookmark-jump (bookmark-bmenu-bookmark))
1831   (bury-buffer (other-buffer))
1832   (delete-other-windows))
1833
1834
1835 (defun bookmark-bmenu-2-window ()
1836   "Select this line's bookmark, with previous buffer in second window."
1837   (interactive)
1838   (let ((bmrk (bookmark-bmenu-bookmark))
1839         (menu (current-buffer))
1840         (pop-up-windows t))
1841     (delete-other-windows)
1842     (switch-to-buffer (other-buffer) nil t)
1843     (bookmark--jump-via bmrk 'pop-to-buffer)
1844     (bury-buffer menu)))
1845
1846
1847 (defun bookmark-bmenu-this-window ()
1848   "Select this line's bookmark in this window."
1849   (interactive)
1850   (bookmark-jump (bookmark-bmenu-bookmark)))
1851
1852
1853 (defun bookmark-bmenu-other-window ()
1854   "Select this line's bookmark in other window, leaving bookmark menu visible."
1855   (interactive)
1856   (let ((bookmark (bookmark-bmenu-bookmark)))
1857     (bookmark--jump-via bookmark 'switch-to-buffer-other-window)))
1858
1859
1860 (defun bookmark-bmenu-switch-other-window ()
1861   "Make the other window select this line's bookmark.
1862 The current window remains selected."
1863   (interactive)
1864   (let ((bookmark (bookmark-bmenu-bookmark))
1865         (pop-up-windows t)
1866         same-window-buffer-names
1867         same-window-regexps)
1868     (bookmark--jump-via bookmark 'display-buffer)))
1869
1870 (defun bookmark-bmenu-other-window-with-mouse (event)
1871   "Select bookmark at the mouse pointer in other window, leaving bookmark menu visible."
1872   (interactive "e")
1873   (with-current-buffer (window-buffer (posn-window (event-end event)))
1874     (save-excursion
1875       (goto-char (posn-point (event-end event)))
1876       (bookmark-bmenu-other-window))))
1877
1878
1879 (defun bookmark-bmenu-show-annotation ()
1880   "Show the annotation for the current bookmark in another window."
1881   (interactive)
1882   (let ((bookmark (bookmark-bmenu-bookmark)))
1883     (bookmark-show-annotation bookmark)))
1884
1885
1886 (defun bookmark-bmenu-show-all-annotations ()
1887   "Show the annotation for all bookmarks in another window."
1888   (interactive)
1889   (bookmark-show-all-annotations))
1890
1891
1892 (defun bookmark-bmenu-edit-annotation ()
1893   "Edit the annotation for the current bookmark in another window."
1894   (interactive)
1895   (let ((bookmark (bookmark-bmenu-bookmark)))
1896     (bookmark-edit-annotation bookmark)))
1897
1898
1899 (defun bookmark-bmenu-unmark (&optional backup)
1900   "Cancel all requested operations on bookmark on this line and move down.
1901 Optional BACKUP means move up."
1902   (interactive "P")
1903   (beginning-of-line)
1904   (bookmark-bmenu-ensure-position)
1905   (with-buffer-modified-unmodified
1906    (let ((inhibit-read-only t))
1907      (delete-char 1)
1908      ;; any flags to reset according to circumstances?  How about a
1909      ;; flag indicating whether this bookmark is being visited?
1910      ;; well, we don't have this now, so maybe later.
1911      (insert " "))
1912    (forward-line (if backup -1 1))
1913    (bookmark-bmenu-ensure-position)))
1914
1915
1916 (defun bookmark-bmenu-backup-unmark ()
1917   "Move up and cancel all requested operations on bookmark on line above."
1918   (interactive)
1919   (forward-line -1)
1920   (bookmark-bmenu-ensure-position)
1921   (bookmark-bmenu-unmark)
1922   (forward-line -1)
1923   (bookmark-bmenu-ensure-position))
1924
1925
1926 (defun bookmark-bmenu-delete ()
1927   "Mark bookmark on this line to be deleted.
1928 To carry out the deletions that you've marked, use \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-execute-deletions]."
1929   (interactive)
1930   (beginning-of-line)
1931   (bookmark-bmenu-ensure-position)
1932   (with-buffer-modified-unmodified
1933    (let ((inhibit-read-only t))
1934      (delete-char 1)
1935      (insert ?D)
1936      (forward-line 1)
1937      (bookmark-bmenu-ensure-position))))
1938
1939
1940 (defun bookmark-bmenu-delete-backwards ()
1941   "Mark bookmark on this line to be deleted, then move up one line.
1942 To carry out the deletions that you've marked, use \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-execute-deletions]."
1943   (interactive)
1944   (bookmark-bmenu-delete)
1945   (forward-line -2)
1946   (bookmark-bmenu-ensure-position)
1947   (forward-line 1)
1948   (bookmark-bmenu-ensure-position))
1949
1950
1951 (defun bookmark-bmenu-execute-deletions ()
1952   "Delete bookmarks flagged `D'."
1953   (interactive)
1954   (message "Deleting bookmarks...")
1955   (let ((o-point  (point))
1956         (o-str    (save-excursion
1957                     (beginning-of-line)
1958                     (unless (looking-at "^D")
1959                       (buffer-substring
1960                        (point)
1961                        (progn (end-of-line) (point))))))
1962         (o-col     (current-column)))
1963     (goto-char (point-min))
1964     (forward-line 1)
1965     (while (re-search-forward "^D" (point-max) t)
1966       (bookmark-delete (bookmark-bmenu-bookmark) t)) ; pass BATCH arg
1967     (bookmark-bmenu-list)
1968     (if o-str
1969         (progn
1970           (goto-char (point-min))
1971           (search-forward o-str)
1972           (beginning-of-line)
1973           (forward-char o-col))
1974       (goto-char o-point))
1975     (beginning-of-line)
1976     (message "Deleting bookmarks...done")
1977     ))
1978
1979
1980 (defun bookmark-bmenu-rename ()
1981   "Rename bookmark on current line.  Prompts for a new name."
1982   (interactive)
1983   (let ((bmrk (bookmark-bmenu-bookmark))
1984         (thispoint (point)))
1985     (bookmark-rename bmrk)
1986     (goto-char thispoint)))
1987
1988
1989 (defun bookmark-bmenu-locate ()
1990   "Display location of this bookmark.  Displays in the minibuffer."
1991   (interactive)
1992   (let ((bmrk (bookmark-bmenu-bookmark)))
1993     (message "%s" (bookmark-location bmrk))))
1994
1995 (defun bookmark-bmenu-relocate ()
1996   "Change the file path of the bookmark on the current line,
1997   prompting with completion for the new path."
1998   (interactive)
1999   (let ((bmrk (bookmark-bmenu-bookmark))
2000         (thispoint (point)))
2001     (bookmark-relocate bmrk)
2002     (goto-char thispoint)))
2003
2004 ;;; Bookmark-bmenu search
2005
2006 ;; Store keyboard input for incremental search.
2007 (defvar bookmark-search-pattern)
2008
2009 (defun bookmark-read-search-input ()
2010   "Read each keyboard input and add it to `bookmark-search-pattern'."
2011   (let ((prompt       (propertize "Pattern: " 'face 'minibuffer-prompt))
2012         ;; (inhibit-quit t) ; inhibit-quit is evil.  Use it with extreme care!
2013         (tmp-list     ()))
2014     (while
2015         (let ((char (read-key (concat prompt bookmark-search-pattern))))
2016           (pcase char
2017             ((or ?\e ?\r) nil) ; RET or ESC break the search loop.
2018             (?\C-g (setq bookmark-quit-flag t) nil)
2019             (?\d (pop tmp-list) t) ; Delete last char of pattern with DEL
2020             (_
2021              (if (characterp char)
2022                  (push char tmp-list)
2023                (setq unread-command-events
2024                      (nconc (mapcar 'identity
2025                                     (this-single-command-raw-keys))
2026                             unread-command-events))
2027                nil))))
2028       (setq bookmark-search-pattern
2029             (apply 'string (reverse tmp-list))))))
2030
2031
2032 (defun bookmark-bmenu-filter-alist-by-regexp (regexp)
2033   "Filter `bookmark-alist' with bookmarks matching REGEXP and rebuild list."
2034   (let ((bookmark-alist
2035          (cl-loop for i in bookmark-alist
2036                   when (string-match regexp (car i)) collect i into new
2037                   finally return new)))
2038     (bookmark-bmenu-list)))
2039
2040
2041 ;;;###autoload
2042 (defun bookmark-bmenu-search ()
2043   "Incremental search of bookmarks, hiding the non-matches as we go."
2044   (interactive)
2045   (let ((bmk (bookmark-bmenu-bookmark))
2046         (bookmark-search-pattern "")
2047         (timer (run-with-idle-timer
2048                 bookmark-search-delay 'repeat
2049                 #'(lambda ()
2050                     (bookmark-bmenu-filter-alist-by-regexp
2051                      bookmark-search-pattern)))))
2052     (unwind-protect
2053         (bookmark-read-search-input)
2054       (cancel-timer timer)
2055       (message nil)
2056       (when bookmark-quit-flag        ; C-g hit restore menu list.
2057         (bookmark-bmenu-list) (bookmark-bmenu-goto-bookmark bmk))
2058       (setq bookmark-quit-flag nil))))
2059
2060 (defun bookmark-bmenu-goto-bookmark (name)
2061   "Move point to bookmark with name NAME."
2062   (goto-char (point-min))
2063   (while (not (equal name (bookmark-bmenu-bookmark)))
2064     (forward-line 1))
2065   (forward-line 0))
2066
2067
2068 \f
2069 ;;; Menu bar stuff.  Prefix is "bookmark-menu".
2070
2071 (defun bookmark-menu-popup-paned-menu (event name entries)
2072   "Pop up multi-paned menu at EVENT, return string chosen from ENTRIES.
2073 That is, ENTRIES is a list of strings which appear as the choices
2074 in the menu.
2075 The number of panes depends on the number of entries.
2076 The visible entries are truncated to `bookmark-menu-length', but the
2077 strings returned are not."
2078   (let ((f-height (/ (frame-height) 2))
2079         (pane-list nil)
2080         (iter 0))
2081     (while entries
2082       (let (lst
2083             (count 0))
2084         (while (and (< count f-height) entries)
2085           (let ((str (car entries)))
2086             (push (cons
2087                    (if (> (length str) bookmark-menu-length)
2088                        (substring str 0 bookmark-menu-length)
2089                      str)
2090                    str)
2091                   lst)
2092             (setq entries (cdr entries))
2093             (setq count (1+ count))))
2094         (setq iter (1+ iter))
2095         (push (cons
2096                (format "-*- %s (%d) -*-" name iter)
2097                (nreverse lst))
2098               pane-list)))
2099
2100     ;; Popup the menu and return the string.
2101     (x-popup-menu event (cons (concat "-*- " name " -*-")
2102                               (nreverse pane-list)))))
2103
2104
2105 ;; Thanks to Roland McGrath for fixing menubar.el so that the
2106 ;; following works, and for explaining what to do to make it work.
2107
2108 ;; We MUST autoload EACH form used to set up this variable's value, so
2109 ;; that the whole job is done in loaddefs.el.
2110
2111 ;; Emacs menubar stuff.
2112
2113 ;;;###autoload
2114 (defvar menu-bar-bookmark-map
2115   (let ((map (make-sparse-keymap "Bookmark functions")))
2116     (bindings--define-key map [load]
2117       '(menu-item "Load a Bookmark File..." bookmark-load
2118                   :help "Load bookmarks from a bookmark file)"))
2119     (bindings--define-key map [write]
2120       '(menu-item "Save Bookmarks As..." bookmark-write
2121                   :help "Write bookmarks to a file (reading the file name with the minibuffer)"))
2122     (bindings--define-key map [save]
2123       '(menu-item "Save Bookmarks" bookmark-save
2124                   :help "Save currently defined bookmarks"))
2125     (bindings--define-key map [edit]
2126       '(menu-item "Edit Bookmark List" bookmark-bmenu-list
2127                   :help "Display a list of existing bookmarks"))
2128     (bindings--define-key map [delete]
2129       '(menu-item "Delete Bookmark..." bookmark-delete
2130                   :help "Delete a bookmark from the bookmark list"))
2131     (bindings--define-key map [rename]
2132       '(menu-item "Rename Bookmark..." bookmark-rename
2133                   :help "Change the name of a bookmark"))
2134     (bindings--define-key map [locate]
2135       '(menu-item "Insert Location..." bookmark-locate
2136                   :help "Insert the name of the file associated with a bookmark"))
2137     (bindings--define-key map [insert]
2138       '(menu-item "Insert Contents..." bookmark-insert
2139                   :help "Insert the text of the file pointed to by a bookmark"))
2140     (bindings--define-key map [set]
2141       '(menu-item "Set Bookmark..." bookmark-set
2142                   :help "Set a bookmark named inside a file."))
2143     (bindings--define-key map [jump]
2144       '(menu-item "Jump to Bookmark..." bookmark-jump
2145                   :help "Jump to a bookmark (a point in some file)"))
2146     map))
2147
2148 ;;;###autoload
2149 (defalias 'menu-bar-bookmark-map menu-bar-bookmark-map)
2150
2151 ;; make bookmarks appear toward the right side of the menu.
2152 (if (boundp 'menu-bar-final-items)
2153     (if menu-bar-final-items
2154         (push 'bookmark menu-bar-final-items))
2155   (setq menu-bar-final-items '(bookmark)))
2156
2157 ;;;; end bookmark menu stuff ;;;;
2158
2159 \f
2160 ;; Load Hook
2161 (defvar bookmark-load-hook nil
2162   "Hook run at the end of loading library `bookmark.el'.")
2163
2164 ;; Exit Hook, called from kill-emacs-hook
2165 (define-obsolete-variable-alias 'bookmark-exit-hooks
2166   'bookmark-exit-hook "22.1")
2167 (defvar bookmark-exit-hook nil
2168   "Hook run when Emacs exits.")
2169
2170 (defun bookmark-exit-hook-internal ()
2171   "Save bookmark state, if necessary, at Emacs exit time.
2172 This also runs `bookmark-exit-hook'."
2173   (run-hooks 'bookmark-exit-hook)
2174   (and bookmark-alist
2175        (bookmark-time-to-save-p t)
2176        (bookmark-save)))
2177
2178 (unless noninteractive
2179   (add-hook 'kill-emacs-hook 'bookmark-exit-hook-internal))
2180
2181 (defun bookmark-unload-function ()
2182   "Unload the Bookmark library."
2183   (when bookmark-save-flag (bookmark-save))
2184   ;; continue standard unloading
2185   nil)
2186
2187
2188 (run-hooks 'bookmark-load-hook)
2189
2190 (provide 'bookmark)
2191
2192 ;;; bookmark.el ends here