lisp/bookmark.el

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