code.delx.au - gnu-emacs/blob - 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 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 (expand-file-name bookmark-old-default-file))
 962             (not (file-exists-p (expand-file-name bookmark-default-file)))
 963             (rename-file (expand-file-name bookmark-old-default-file)
 964                          (expand-file-name bookmark-default-file)))
 965            ;; return t so the `and' will continue...
 966            t)
 967
 968        (file-readable-p (expand-file-name 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     (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         (forward-str   (bookmark-get-front-context-string bmk-record))
1120         (behind-str    (bookmark-get-rear-context-string bmk-record))
1121         (place         (bookmark-get-position bmk-record)))
1122     (if (not file)
1123         (signal 'bookmark-error-no-filename (list 'stringp file))
1124       (set-buffer (find-file-noselect file))
1125       (if place (goto-char place))
1126       ;; Go searching forward first.  Then, if forward-str exists and
1127       ;; was found in the file, we can search backward for behind-str.
1128       ;; Rationale is that if text was inserted between the two in the
1129       ;; file, it's better to be put before it so you can read it,
1130       ;; rather than after and remain perhaps unaware of the changes.
1131       (if forward-str
1132           (if (search-forward forward-str (point-max) t)
1133               (goto-char (match-beginning 0))))
1134       (if behind-str
1135           (if (search-backward behind-str (point-min) t)
1136               (goto-char (match-end 0)))))
1137     nil))
1138
1139 ;;;###autoload
1140 (defun bookmark-relocate (bookmark)
1141   "Relocate BOOKMARK to another file (reading file name with minibuffer).
1142 BOOKMARK is a bookmark name (a string), not a bookmark record.
1143
1144 This makes an already existing bookmark point to that file, instead of
1145 the one it used to point at.  Useful when a file has been renamed
1146 after a bookmark was set in it."
1147   (interactive (list (bookmark-completing-read "Bookmark to relocate")))
1148   (bookmark-maybe-historicize-string bookmark)
1149   (bookmark-maybe-load-default-file)
1150   (let* ((bmrk-filename (bookmark-get-filename bookmark))
1151          (newloc (expand-file-name
1152                   (read-file-name
1153                    (format "Relocate %s to: " bookmark)
1154                    (file-name-directory bmrk-filename)))))
1155     (bookmark-set-filename bookmark newloc)
1156     (setq bookmark-alist-modification-count
1157           (1+ bookmark-alist-modification-count))
1158     (if (bookmark-time-to-save-p)
1159         (bookmark-save))
1160     (bookmark-bmenu-surreptitiously-rebuild-list)))
1161
1162
1163 ;;;###autoload
1164 (defun bookmark-insert-location (bookmark &optional no-history)
1165   "Insert the name of the file associated with BOOKMARK.
1166 BOOKMARK is a bookmark name (a string), not a bookmark record.
1167
1168 Optional second arg NO-HISTORY means don't record this in the
1169 minibuffer history list `bookmark-history'."
1170   (interactive (list (bookmark-completing-read "Insert bookmark location")))
1171   (or no-history (bookmark-maybe-historicize-string bookmark))
1172   (let ((start (point)))
1173     (prog1
1174         (insert (bookmark-location bookmark)) ; *Return this line*
1175       (if (display-mouse-p)
1176           (add-text-properties
1177            start
1178            (save-excursion (re-search-backward
1179                             "[^ \t]")
1180                            (1+ (point)))
1181            '(mouse-face highlight
1182              follow-link t
1183              help-echo "mouse-2: go to this bookmark in other window"))))))
1184
1185 ;;;###autoload
1186 (defalias 'bookmark-locate 'bookmark-insert-location)
1187
1188 (defun bookmark-location (bookmark)
1189   "Return the name of the file associated with BOOKMARK, or nil if none.
1190 BOOKMARK may be a bookmark name (a string) or a bookmark record."
1191   (bookmark-maybe-load-default-file)
1192   (bookmark-get-filename bookmark))
1193
1194
1195 ;;;###autoload
1196 (defun bookmark-rename (old &optional new)
1197   "Change the name of OLD bookmark to NEW name.
1198 If called from keyboard, prompt for OLD and NEW.  If called from
1199 menubar, select OLD from a menu and prompt for NEW.
1200
1201 Both OLD and NEW are bookmark names (strings), never bookmark records.
1202
1203 If called from Lisp, prompt for NEW if only OLD was passed as an
1204 argument.  If called with two strings, then no prompting is done.  You
1205 must pass at least OLD when calling from Lisp.
1206
1207 While you are entering the new name, consecutive C-w's insert
1208 consecutive words from the text of the buffer into the new bookmark
1209 name."
1210   (interactive (list (bookmark-completing-read "Old bookmark name")))
1211   (bookmark-maybe-historicize-string old)
1212   (bookmark-maybe-load-default-file)
1213
1214   (setq bookmark-yank-point (point))
1215   (setq bookmark-current-buffer (current-buffer))
1216   (let ((newname
1217          (or new   ; use second arg, if non-nil
1218              (read-from-minibuffer
1219               "New name: "
1220               nil
1221               (let ((now-map (copy-keymap minibuffer-local-map)))
1222                 (define-key now-map "\C-w" 'bookmark-yank-word)
1223                 now-map)
1224               nil
1225               'bookmark-history))))
1226     (bookmark-set-name old newname)
1227     (setq bookmark-current-bookmark newname)
1228     (bookmark-bmenu-surreptitiously-rebuild-list)
1229     (setq bookmark-alist-modification-count
1230           (1+ bookmark-alist-modification-count))
1231     (if (bookmark-time-to-save-p)
1232         (bookmark-save))))
1233
1234
1235 ;;;###autoload
1236 (defun bookmark-insert (bookmark)
1237   "Insert the text of the file pointed to by bookmark BOOKMARK.
1238 BOOKMARK is a bookmark name (a string), not a bookmark record.
1239
1240 You may have a problem using this function if the value of variable
1241 `bookmark-alist' is nil.  If that happens, you need to load in some
1242 bookmarks.  See help on function `bookmark-load' for more about
1243 this."
1244   (interactive (list (bookmark-completing-read "Insert bookmark contents")))
1245   (bookmark-maybe-historicize-string bookmark)
1246   (bookmark-maybe-load-default-file)
1247   (let ((orig-point (point))
1248         (str-to-insert
1249          (save-current-buffer
1250            (bookmark-handle-bookmark bookmark)
1251            (buffer-string))))
1252     (insert str-to-insert)
1253     (push-mark)
1254     (goto-char orig-point)))
1255
1256
1257 ;;;###autoload
1258 (defun bookmark-delete (bookmark &optional batch)
1259   "Delete BOOKMARK from the bookmark list.
1260 BOOKMARK is a bookmark name (a string), not a bookmark record.
1261
1262 Removes only the first instance of a bookmark with that name.  If
1263 there are one or more other bookmarks with the same name, they will
1264 not be deleted.  Defaults to the \"current\" bookmark (that is, the
1265 one most recently used in this file, if any).
1266 Optional second arg BATCH means don't update the bookmark list buffer,
1267 probably because we were called from there."
1268   (interactive
1269    (list (bookmark-completing-read "Delete bookmark"
1270                                    bookmark-current-bookmark)))
1271   (bookmark-maybe-historicize-string bookmark)
1272   (bookmark-maybe-load-default-file)
1273   (let ((will-go (bookmark-get-bookmark bookmark 'noerror)))
1274     (setq bookmark-alist (delq will-go bookmark-alist))
1275     ;; Added by db, nil bookmark-current-bookmark if the last
1276     ;; occurrence has been deleted
1277     (or (bookmark-get-bookmark bookmark-current-bookmark 'noerror)
1278         (setq bookmark-current-bookmark nil)))
1279   (unless batch
1280     (bookmark-bmenu-surreptitiously-rebuild-list))
1281   (setq bookmark-alist-modification-count
1282         (1+ bookmark-alist-modification-count))
1283   (when (bookmark-time-to-save-p)
1284     (bookmark-save)))
1285
1286
1287 (defun bookmark-time-to-save-p (&optional final-time)
1288   "Return t if it is time to save bookmarks to disk, nil otherwise.
1289 Optional argument FINAL-TIME means this is being called when Emacs
1290 is being killed, so save even if `bookmark-save-flag' is a number and
1291 is greater than `bookmark-alist-modification-count'."
1292   ;; By Gregory M. Saunders <saunders{_AT_}cis.ohio-state.edu>
1293   (cond (final-time
1294          (and (> bookmark-alist-modification-count 0)
1295               bookmark-save-flag))
1296         ((numberp bookmark-save-flag)
1297          (>= bookmark-alist-modification-count bookmark-save-flag))
1298         (t
1299          nil)))
1300
1301
1302 ;;;###autoload
1303 (defun bookmark-write ()
1304   "Write bookmarks to a file (reading the file name with the minibuffer).
1305 Don't use this in Lisp programs; use `bookmark-save' instead."
1306   (interactive)
1307   (bookmark-maybe-load-default-file)
1308   (bookmark-save t))
1309
1310
1311 ;;;###autoload
1312 (defun bookmark-save (&optional parg file)
1313   "Save currently defined bookmarks.
1314 Saves by default in the file defined by the variable
1315 `bookmark-default-file'.  With a prefix arg, save it in file FILE
1316 \(second argument).
1317
1318 If you are calling this from Lisp, the two arguments are PARG and
1319 FILE, and if you just want it to write to the default file, then
1320 pass no arguments.  Or pass in nil and FILE, and it will save in FILE
1321 instead.  If you pass in one argument, and it is non-nil, then the
1322 user will be interactively queried for a file to save in.
1323
1324 When you want to load in the bookmarks from a file, use
1325 `bookmark-load', \\[bookmark-load].  That function will prompt you
1326 for a file, defaulting to the file defined by variable
1327 `bookmark-default-file'."
1328   (interactive "P")
1329   (bookmark-maybe-load-default-file)
1330   (cond
1331    ((and (null parg) (null file))
1332     ;;whether interactive or not, write to default file
1333     (bookmark-write-file bookmark-default-file))
1334    ((and (null parg) file)
1335     ;;whether interactive or not, write to given file
1336     (bookmark-write-file file))
1337    ((and parg (not file))
1338     ;;have been called interactively w/ prefix arg
1339     (let ((file (read-file-name "File to save bookmarks in: ")))
1340       (bookmark-write-file file)))
1341    (t ; someone called us with prefix-arg *and* a file, so just write to file
1342     (bookmark-write-file file)))
1343   ;; signal that we have synced the bookmark file by setting this to
1344   ;; 0.  If there was an error at any point before, it will not get
1345   ;; set, which is what we want.
1346   (setq bookmark-alist-modification-count 0))
1347
1348
1349 \f
1350 (defun bookmark-write-file (file)
1351   "Write `bookmark-alist' to FILE."
1352   (bookmark-maybe-message "Saving bookmarks to file %s..." file)
1353   (with-current-buffer (get-buffer-create " *Bookmarks*")
1354     (goto-char (point-min))
1355     (delete-region (point-min) (point-max))
1356     (let ((print-length nil)
1357           (print-level nil))
1358       (bookmark-insert-file-format-version-stamp)
1359       (insert "(")
1360       ;; Rather than a single call to `pp' we make one per bookmark.
1361       ;; Apparently `pp' has a poor algorithmic complexity, so this
1362       ;; scales a lot better.  bug#4485.
1363       (dolist (i bookmark-alist) (pp i (current-buffer)))
1364       (insert ")")
1365       (let ((version-control
1366              (cond
1367               ((null bookmark-version-control) nil)
1368               ((eq 'never bookmark-version-control) 'never)
1369               ((eq 'nospecial bookmark-version-control) version-control)
1370               (t t))))
1371         (condition-case nil
1372             (write-region (point-min) (point-max) file)
1373           (file-error (message "Can't write %s" file)))
1374         (kill-buffer (current-buffer))
1375         (bookmark-maybe-message
1376          "Saving bookmarks to file %s...done" file)))))
1377
1378
1379 (defun bookmark-import-new-list (new-list)
1380   "Add NEW-LIST of bookmarks to `bookmark-alist'.
1381 Rename new bookmarks as needed using suffix \"<N>\" (N=1,2,3...), when
1382 they conflict with existing bookmark names."
1383   (let ((names (bookmark-all-names)))
1384     (dolist (full-record new-list)
1385       (bookmark-maybe-rename full-record names)
1386       (setq bookmark-alist (nconc bookmark-alist (list full-record)))
1387       (push (bookmark-name-from-full-record full-record) names))))
1388
1389
1390 (defun bookmark-maybe-rename (full-record names)
1391   "Rename bookmark FULL-RECORD if its current name is already used.
1392 This is a helper for `bookmark-import-new-list'."
1393   (let ((found-name (bookmark-name-from-full-record full-record)))
1394     (if (member found-name names)
1395         ;; We've got a conflict, so generate a new name
1396         (let ((count 2)
1397               (new-name found-name))
1398           (while (member new-name names)
1399             (setq new-name (concat found-name (format "<%d>" count)))
1400             (setq count (1+ count)))
1401           (bookmark-set-name full-record new-name)))))
1402
1403
1404 ;;;###autoload
1405 (defun bookmark-load (file &optional overwrite no-msg)
1406   "Load bookmarks from FILE (which must be in bookmark format).
1407 Appends loaded bookmarks to the front of the list of bookmarks.  If
1408 optional second argument OVERWRITE is non-nil, existing bookmarks are
1409 destroyed.  Optional third arg NO-MSG means don't display any messages
1410 while loading.
1411
1412 If you load a file that doesn't contain a proper bookmark alist, you
1413 will corrupt Emacs's bookmark list.  Generally, you should only load
1414 in files that were created with the bookmark functions in the first
1415 place.  Your own personal bookmark file, `~/.emacs.bmk', is
1416 maintained automatically by Emacs; you shouldn't need to load it
1417 explicitly.
1418
1419 If you load a file containing bookmarks with the same names as
1420 bookmarks already present in your Emacs, the new bookmarks will get
1421 unique numeric suffixes \"<2>\", \"<3>\", ... following the same
1422 method buffers use to resolve name collisions."
1423   (interactive
1424    (list (read-file-name
1425           (format "Load bookmarks from: (%s) "
1426                   bookmark-default-file)
1427           ;;Default might not be used often,
1428           ;;but there's no better default, and
1429           ;;I guess it's better than none at all.
1430           "~/" bookmark-default-file 'confirm)))
1431   (setq file (expand-file-name file))
1432   (if (not (file-readable-p file))
1433       (error "Cannot read bookmark file %s" file)
1434     (if (null no-msg)
1435         (bookmark-maybe-message "Loading bookmarks from %s..." file))
1436     (with-current-buffer (let ((enable-local-variables nil))
1437                            (find-file-noselect file))
1438       (goto-char (point-min))
1439       (bookmark-maybe-upgrade-file-format)
1440       (let ((blist (bookmark-alist-from-buffer)))
1441         (if (listp blist)
1442             (progn
1443               (if overwrite
1444                   (progn
1445                     (setq bookmark-alist blist)
1446                     (setq bookmark-alist-modification-count 0))
1447                 ;; else
1448                 (bookmark-import-new-list blist)
1449                 (setq bookmark-alist-modification-count
1450                       (1+ bookmark-alist-modification-count)))
1451               (if (string-equal
1452                    (expand-file-name bookmark-default-file)
1453                    file)
1454                   (setq bookmarks-already-loaded t))
1455               (bookmark-bmenu-surreptitiously-rebuild-list))
1456           (error "Invalid bookmark list in %s" file)))
1457       (kill-buffer (current-buffer)))
1458     (if (null no-msg)
1459         (bookmark-maybe-message "Loading bookmarks from %s...done" file))))
1460
1461
1462 \f
1463 ;;; Code supporting the dired-like bookmark menu.
1464 ;; Prefix is "bookmark-bmenu" for "buffer-menu":
1465
1466
1467 (defvar bookmark-bmenu-hidden-bookmarks ())
1468
1469
1470 (defvar bookmark-bmenu-mode-map
1471   (let ((map (make-keymap)))
1472     (suppress-keymap map t)
1473     (define-key map "q" 'quit-window)
1474     (define-key map "v" 'bookmark-bmenu-select)
1475     (define-key map "w" 'bookmark-bmenu-locate)
1476     (define-key map "2" 'bookmark-bmenu-2-window)
1477     (define-key map "1" 'bookmark-bmenu-1-window)
1478     (define-key map "j" 'bookmark-bmenu-this-window)
1479     (define-key map "\C-c\C-c" 'bookmark-bmenu-this-window)
1480     (define-key map "f" 'bookmark-bmenu-this-window)
1481     (define-key map "\C-m" 'bookmark-bmenu-this-window)
1482     (define-key map "o" 'bookmark-bmenu-other-window)
1483     (define-key map "\C-o" 'bookmark-bmenu-switch-other-window)
1484     (define-key map "s" 'bookmark-bmenu-save)
1485     (define-key map "k" 'bookmark-bmenu-delete)
1486     (define-key map "\C-d" 'bookmark-bmenu-delete-backwards)
1487     (define-key map "x" 'bookmark-bmenu-execute-deletions)
1488     (define-key map "d" 'bookmark-bmenu-delete)
1489     (define-key map " " 'next-line)
1490     (define-key map "n" 'next-line)
1491     (define-key map "p" 'previous-line)
1492     (define-key map "\177" 'bookmark-bmenu-backup-unmark)
1493     (define-key map "?" 'describe-mode)
1494     (define-key map "u" 'bookmark-bmenu-unmark)
1495     (define-key map "m" 'bookmark-bmenu-mark)
1496     (define-key map "l" 'bookmark-bmenu-load)
1497     (define-key map "r" 'bookmark-bmenu-rename)
1498     (define-key map "R" 'bookmark-bmenu-relocate)
1499     (define-key map "t" 'bookmark-bmenu-toggle-filenames)
1500     (define-key map "a" 'bookmark-bmenu-show-annotation)
1501     (define-key map "A" 'bookmark-bmenu-show-all-annotations)
1502     (define-key map "e" 'bookmark-bmenu-edit-annotation)
1503     ;; The original binding of M-g hides the M-g prefix map.
1504     ;; If someone has a better idea than M-g s, I'm open to suggestions.
1505     (define-key map [?\M-g ?s] 'bookmark-bmenu-search)
1506     (define-key map [mouse-2] 'bookmark-bmenu-other-window-with-mouse)
1507     map))
1508
1509 ;; Bookmark Buffer Menu mode is suitable only for specially formatted
1510 ;; data.
1511 (put 'bookmark-bmenu-mode 'mode-class 'special)
1512
1513
1514 ;; todo: need to display whether or not bookmark exists as a buffer in
1515 ;; flag column.
1516
1517 ;; Format:
1518 ;; FLAGS  BOOKMARK [ LOCATION ]
1519
1520
1521 (defun bookmark-bmenu-surreptitiously-rebuild-list ()
1522   "Rebuild the Bookmark List if it exists.
1523 Don't affect the buffer ring order."
1524   (if (get-buffer "*Bookmark List*")
1525       (save-excursion
1526         (save-window-excursion
1527           (bookmark-bmenu-list)))))
1528
1529
1530 ;;;###autoload
1531 (defun bookmark-bmenu-list ()
1532   "Display a list of existing bookmarks.
1533 The list is displayed in a buffer named `*Bookmark List*'.
1534 The leftmost column displays a D if the bookmark is flagged for
1535 deletion, or > if it is flagged for displaying."
1536   (interactive)
1537   (bookmark-maybe-load-default-file)
1538   (let ((buf (get-buffer-create "*Bookmark List*")))
1539     (if (called-interactively-p 'interactive)
1540         (if (or (window-dedicated-p) (window-minibuffer-p))
1541             (pop-to-buffer buf)
1542           (switch-to-buffer buf))
1543       (set-buffer buf)))
1544   (let ((inhibit-read-only t))
1545     (erase-buffer)
1546     (insert "% Bookmark\n- --------\n")
1547     (add-text-properties (point-min) (point)
1548                          '(font-lock-face bookmark-menu-heading))
1549     (dolist (full-record (bookmark-maybe-sort-alist))
1550       (let ((name        (bookmark-name-from-full-record full-record))
1551             (annotation  (bookmark-get-annotation full-record))
1552             (start       (point))
1553             end)
1554         ;; if a bookmark has an annotation, prepend a "*"
1555         ;; in the list of bookmarks.
1556         (insert (if (and annotation (not (string-equal annotation "")))
1557                     " *" "  ")
1558                 name)
1559         (setq end (point))
1560         (put-text-property
1561          (+ bookmark-bmenu-marks-width start) end 'bookmark-name-prop name)
1562         (when (display-mouse-p)
1563           (add-text-properties
1564            (+ bookmark-bmenu-marks-width start) end
1565            '(mouse-face highlight
1566              follow-link t
1567              help-echo "mouse-2: go to this bookmark in other window")))
1568         (insert "\n")))
1569     (set-buffer-modified-p (not (= bookmark-alist-modification-count 0)))
1570     (goto-char (point-min))
1571     (forward-line 2)
1572     (bookmark-bmenu-mode)
1573     (if bookmark-bmenu-toggle-filenames
1574         (bookmark-bmenu-toggle-filenames t))))
1575
1576 ;;;###autoload
1577 (defalias 'list-bookmarks 'bookmark-bmenu-list)
1578 ;;;###autoload
1579 (defalias 'edit-bookmarks 'bookmark-bmenu-list)
1580
1581
1582
1583 (defun bookmark-bmenu-mode ()
1584   "Major mode for editing a list of bookmarks.
1585 Each line describes one of the bookmarks in Emacs.
1586 Letters do not insert themselves; instead, they are commands.
1587 Bookmark names preceded by a \"*\" have annotations.
1588 \\<bookmark-bmenu-mode-map>
1589 \\[bookmark-bmenu-mark] -- mark bookmark to be displayed.
1590 \\[bookmark-bmenu-select] -- select bookmark of line point is on.
1591   Also show bookmarks marked using m in other windows.
1592 \\[bookmark-bmenu-toggle-filenames] -- toggle displaying of filenames (they may obscure long bookmark names).
1593 \\[bookmark-bmenu-locate] -- display (in minibuffer) location of this bookmark.
1594 \\[bookmark-bmenu-1-window] -- select this bookmark in full-frame window.
1595 \\[bookmark-bmenu-2-window] -- select this bookmark in one window,
1596   together with bookmark selected before this one in another window.
1597 \\[bookmark-bmenu-this-window] -- select this bookmark in place of the bookmark menu buffer.
1598 \\[bookmark-bmenu-other-window] -- select this bookmark in another window,
1599   so the bookmark menu bookmark remains visible in its window.
1600 \\[bookmark-bmenu-switch-other-window] -- switch the other window to this bookmark.
1601 \\[bookmark-bmenu-rename] -- rename this bookmark (prompts for new name).
1602 \\[bookmark-bmenu-relocate] -- relocate this bookmark's file (prompts for new file).
1603 \\[bookmark-bmenu-delete] -- mark this bookmark to be deleted, and move down.
1604 \\[bookmark-bmenu-delete-backwards] -- mark this bookmark to be deleted, and move up.
1605 \\[bookmark-bmenu-execute-deletions] -- delete bookmarks marked with `\\[bookmark-bmenu-delete]'.
1606 \\[bookmark-bmenu-save] -- save the current bookmark list in the default file.
1607   With a prefix arg, prompts for a file to save in.
1608 \\[bookmark-bmenu-load] -- load in a file of bookmarks (prompts for file.)
1609 \\[bookmark-bmenu-unmark] -- remove all kinds of marks from current line.
1610   With prefix argument, also move up one line.
1611 \\[bookmark-bmenu-backup-unmark] -- back up a line and remove marks.
1612 \\[bookmark-bmenu-show-annotation] -- show the annotation, if it exists, for the current bookmark
1613   in another buffer.
1614 \\[bookmark-bmenu-show-all-annotations] -- show the annotations of all bookmarks in another buffer.
1615 \\[bookmark-bmenu-edit-annotation] -- edit the annotation for the current bookmark."
1616   (kill-all-local-variables)
1617   (use-local-map bookmark-bmenu-mode-map)
1618   (setq truncate-lines t)
1619   (setq buffer-read-only t)
1620   (setq major-mode 'bookmark-bmenu-mode)
1621   (setq mode-name "Bookmark Menu")
1622   (run-mode-hooks 'bookmark-bmenu-mode-hook))
1623
1624
1625 (defun bookmark-bmenu-toggle-filenames (&optional show)
1626   "Toggle whether filenames are shown in the bookmark list.
1627 Optional argument SHOW means show them unconditionally."
1628   (interactive)
1629   (cond
1630    (show
1631     (setq bookmark-bmenu-toggle-filenames nil)
1632     (bookmark-bmenu-show-filenames)
1633     (setq bookmark-bmenu-toggle-filenames t))
1634    (bookmark-bmenu-toggle-filenames
1635     (bookmark-bmenu-hide-filenames)
1636     (setq bookmark-bmenu-toggle-filenames nil))
1637    (t
1638     (bookmark-bmenu-show-filenames)
1639     (setq bookmark-bmenu-toggle-filenames t))))
1640
1641
1642 (defun bookmark-bmenu-show-filenames (&optional force)
1643   "In an interactive bookmark list, show filenames along with bookmarks.
1644 Non-nil FORCE forces a redisplay showing the filenames.  FORCE is used
1645 mainly for debugging, and should not be necessary in normal use."
1646   (if (and (not force) bookmark-bmenu-toggle-filenames)
1647       nil ;already shown, so do nothing
1648     (with-buffer-modified-unmodified
1649      (save-excursion
1650        (save-window-excursion
1651          (goto-char (point-min))
1652          (forward-line 2)
1653          (setq bookmark-bmenu-hidden-bookmarks ())
1654          (let ((inhibit-read-only t))
1655            (while (< (point) (point-max))
1656              (let ((bmrk (bookmark-bmenu-bookmark)))
1657                (push bmrk bookmark-bmenu-hidden-bookmarks)
1658                (let ((start (save-excursion (end-of-line) (point))))
1659                  (move-to-column bookmark-bmenu-file-column t)
1660                  ;; Strip off `mouse-face' from the white spaces region.
1661                  (if (display-mouse-p)
1662                      (remove-text-properties start (point)
1663                                              '(mouse-face nil help-echo nil))))
1664                (delete-region (point) (progn (end-of-line) (point)))
1665                (insert "  ")
1666                ;; Pass the NO-HISTORY arg:
1667                (bookmark-insert-location bmrk t)
1668                (forward-line 1)))))))))
1669
1670
1671 (defun bookmark-bmenu-hide-filenames (&optional force)
1672   "In an interactive bookmark list, hide the filenames of the bookmarks.
1673 Non-nil FORCE forces a redisplay showing the filenames.  FORCE is used
1674 mainly for debugging, and should not be necessary in normal use."
1675   (when (and (not force) bookmark-bmenu-toggle-filenames)
1676     ;; nothing to hide if above is nil
1677     (with-buffer-modified-unmodified
1678      (save-excursion
1679        (goto-char (point-min))
1680        (forward-line 2)
1681        (setq bookmark-bmenu-hidden-bookmarks
1682              (nreverse bookmark-bmenu-hidden-bookmarks))
1683        (let ((inhibit-read-only t))
1684          (while bookmark-bmenu-hidden-bookmarks
1685            (move-to-column bookmark-bmenu-marks-width t)
1686            (bookmark-kill-line)
1687            (let ((name  (pop bookmark-bmenu-hidden-bookmarks))
1688                  (start (point)))
1689              (insert name)
1690              (put-text-property start (point) 'bookmark-name-prop name)
1691              (if (display-mouse-p)
1692                  (add-text-properties
1693                   start (point)
1694                   '(mouse-face
1695                     highlight follow-link t help-echo
1696                     "mouse-2: go to this bookmark in other window"))))
1697            (forward-line 1)))))))
1698
1699
1700 (defun bookmark-bmenu-ensure-position ()
1701   "If point is not on a bookmark line, move it to one.
1702 If before the first bookmark line, move to the first; if after the
1703 last full line, move to the last full line.  The return value is undefined."
1704   (cond ((< (count-lines (point-min) (point)) bookmark-bmenu-header-height)
1705          (goto-char (point-min))
1706          (forward-line bookmark-bmenu-header-height))
1707         ((and (bolp) (eobp))
1708          (beginning-of-line 0))))
1709
1710
1711 (defun bookmark-bmenu-bookmark ()
1712   "Return the bookmark for this line in an interactive bookmark list buffer."
1713   (bookmark-bmenu-ensure-position)
1714   (save-excursion
1715     (beginning-of-line)
1716     (forward-char bookmark-bmenu-marks-width)
1717     (get-text-property (point) 'bookmark-name-prop)))
1718
1719
1720 (defun bookmark-show-annotation (bookmark)
1721   "Display the annotation for bookmark named BOOKMARK in a buffer,
1722 if an annotation exists."
1723   (let ((annotation (bookmark-get-annotation bookmark)))
1724     (if (and annotation (not (string-equal annotation "")))
1725         (save-excursion
1726           (let ((old-buf (current-buffer)))
1727             (pop-to-buffer (get-buffer-create "*Bookmark Annotation*") t)
1728             (delete-region (point-min) (point-max))
1729             ;; (insert (concat "Annotation for bookmark '" bookmark "':\n\n"))
1730             (insert annotation)
1731             (goto-char (point-min))
1732             (pop-to-buffer old-buf))))))
1733
1734
1735 (defun bookmark-show-all-annotations ()
1736   "Display the annotations for all bookmarks in a buffer."
1737   (save-selected-window
1738     (pop-to-buffer (get-buffer-create "*Bookmark Annotation*") t)
1739     (delete-region (point-min) (point-max))
1740     (dolist (full-record bookmark-alist)
1741       (let* ((name (bookmark-name-from-full-record full-record))
1742              (ann  (bookmark-get-annotation full-record)))
1743         (insert (concat name ":\n"))
1744         (if (and ann (not (string-equal ann "")))
1745             ;; insert the annotation, indented by 4 spaces.
1746             (progn
1747               (save-excursion (insert ann) (unless (bolp)
1748                                              (insert "\n")))
1749               (while (< (point) (point-max))
1750                 (beginning-of-line)     ; paranoia
1751                 (insert "    ")
1752                 (forward-line)
1753                 (end-of-line))))))
1754     (goto-char (point-min))))
1755
1756
1757 (defun bookmark-bmenu-mark ()
1758   "Mark bookmark on this line to be displayed by \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-select]."
1759   (interactive)
1760   (beginning-of-line)
1761   (bookmark-bmenu-ensure-position)
1762   (with-buffer-modified-unmodified
1763    (let ((inhibit-read-only t))
1764      (delete-char 1)
1765      (insert ?>)
1766      (forward-line 1)
1767      (bookmark-bmenu-ensure-position))))
1768
1769
1770 (defun bookmark-bmenu-select ()
1771   "Select this line's bookmark; also display bookmarks marked with `>'.
1772 You can mark bookmarks with the \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-mark] command."
1773   (interactive)
1774   (let ((bmrk (bookmark-bmenu-bookmark))
1775         (menu (current-buffer))
1776         (others ())
1777         tem)
1778     (goto-char (point-min))
1779     (while (re-search-forward "^>" nil t)
1780       (setq tem (bookmark-bmenu-bookmark))
1781       (let ((inhibit-read-only t))
1782         (delete-char -1)
1783         (insert ?\s))
1784       (or (string-equal tem bmrk)
1785           (member tem others)
1786           (setq others (cons tem others))))
1787     (setq others (nreverse others)
1788           tem (/ (1- (frame-height)) (1+ (length others))))
1789     (delete-other-windows)
1790     (bookmark-jump bmrk)
1791     (bury-buffer menu)
1792     (if others
1793         (while others
1794           (split-window nil tem)
1795           (other-window 1)
1796           (bookmark-jump (car others))
1797           (setq others (cdr others)))
1798       (other-window 1))))
1799
1800
1801 (defun bookmark-bmenu-any-marks ()
1802   "Return non-nil if any bookmarks are marked in the marks column."
1803   (save-excursion
1804     (goto-char (point-min))
1805     (bookmark-bmenu-ensure-position)
1806     (catch 'found-mark
1807       (while (not (eobp))
1808         (beginning-of-line)
1809         (if (looking-at "^\\S-")
1810             (throw 'found-mark t)
1811           (forward-line 1)))
1812       nil)))
1813
1814
1815 (defun bookmark-bmenu-save (parg)
1816   "Save the current list into a bookmark file.
1817 With a prefix arg, prompts for a file to save them in."
1818   (interactive "P")
1819   (save-excursion
1820     (save-window-excursion
1821       (bookmark-save parg)
1822       (set-buffer-modified-p nil))))
1823
1824
1825 (defun bookmark-bmenu-load ()
1826   "Load the bookmark file and rebuild the bookmark menu-buffer."
1827   (interactive)
1828   (bookmark-bmenu-ensure-position)
1829   (save-excursion
1830     (save-window-excursion
1831       ;; This will call `bookmark-bmenu-list'
1832       (call-interactively 'bookmark-load))))
1833
1834
1835 (defun bookmark-bmenu-1-window ()
1836   "Select this line's bookmark, alone, in full frame."
1837   (interactive)
1838   (bookmark-jump (bookmark-bmenu-bookmark))
1839   (bury-buffer (other-buffer))
1840   (delete-other-windows))
1841
1842
1843 (defun bookmark-bmenu-2-window ()
1844   "Select this line's bookmark, with previous buffer in second window."
1845   (interactive)
1846   (let ((bmrk (bookmark-bmenu-bookmark))
1847         (menu (current-buffer))
1848         (pop-up-windows t))
1849     (delete-other-windows)
1850     (switch-to-buffer (other-buffer))
1851     (let ((bookmark-automatically-show-annotations nil)) ;FIXME: needed?
1852       (bookmark--jump-via bmrk 'pop-to-buffer))
1853     (bury-buffer menu)))
1854
1855
1856 (defun bookmark-bmenu-this-window ()
1857   "Select this line's bookmark in this window."
1858   (interactive)
1859   (bookmark-jump (bookmark-bmenu-bookmark)))
1860
1861
1862 (defun bookmark-bmenu-other-window ()
1863   "Select this line's bookmark in other window, leaving bookmark menu visible."
1864   (interactive)
1865   (let ((bookmark (bookmark-bmenu-bookmark)))
1866     (let ((bookmark-automatically-show-annotations t)) ;FIXME: needed?
1867       (bookmark--jump-via bookmark 'switch-to-buffer-other-window))))
1868
1869
1870 (defun bookmark-bmenu-switch-other-window ()
1871   "Make the other window select this line's bookmark.
1872 The current window remains selected."
1873   (interactive)
1874   (let ((bookmark (bookmark-bmenu-bookmark))
1875         (pop-up-windows t)
1876         same-window-buffer-names
1877         same-window-regexps)
1878     (let ((bookmark-automatically-show-annotations t)) ;FIXME: needed?
1879       (bookmark--jump-via bookmark 'display-buffer))))
1880
1881 (defun bookmark-bmenu-other-window-with-mouse (event)
1882   "Select bookmark at the mouse pointer in other window, leaving bookmark menu visible."
1883   (interactive "e")
1884   (with-current-buffer (window-buffer (posn-window (event-end event)))
1885     (save-excursion
1886       (goto-char (posn-point (event-end event)))
1887       (bookmark-bmenu-other-window))))
1888
1889
1890 (defun bookmark-bmenu-show-annotation ()
1891   "Show the annotation for the current bookmark in another window."
1892   (interactive)
1893   (let ((bookmark (bookmark-bmenu-bookmark)))
1894     (bookmark-show-annotation bookmark)))
1895
1896
1897 (defun bookmark-bmenu-show-all-annotations ()
1898   "Show the annotation for all bookmarks in another window."
1899   (interactive)
1900   (bookmark-show-all-annotations))
1901
1902
1903 (defun bookmark-bmenu-edit-annotation ()
1904   "Edit the annotation for the current bookmark in another window."
1905   (interactive)
1906   (let ((bookmark (bookmark-bmenu-bookmark)))
1907     (bookmark-edit-annotation bookmark)))
1908
1909
1910 (defun bookmark-bmenu-unmark (&optional backup)
1911   "Cancel all requested operations on bookmark on this line and move down.
1912 Optional BACKUP means move up."
1913   (interactive "P")
1914   (beginning-of-line)
1915   (bookmark-bmenu-ensure-position)
1916   (with-buffer-modified-unmodified
1917    (let ((inhibit-read-only t))
1918      (delete-char 1)
1919      ;; any flags to reset according to circumstances?  How about a
1920      ;; flag indicating whether this bookmark is being visited?
1921      ;; well, we don't have this now, so maybe later.
1922      (insert " "))
1923    (forward-line (if backup -1 1))
1924    (bookmark-bmenu-ensure-position)))
1925
1926
1927 (defun bookmark-bmenu-backup-unmark ()
1928   "Move up and cancel all requested operations on bookmark on line above."
1929   (interactive)
1930   (forward-line -1)
1931   (bookmark-bmenu-ensure-position)
1932   (bookmark-bmenu-unmark)
1933   (forward-line -1)
1934   (bookmark-bmenu-ensure-position))
1935
1936
1937 (defun bookmark-bmenu-delete ()
1938   "Mark bookmark on this line to be deleted.
1939 To carry out the deletions that you've marked, use \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-execute-deletions]."
1940   (interactive)
1941   (beginning-of-line)
1942   (bookmark-bmenu-ensure-position)
1943   (with-buffer-modified-unmodified
1944    (let ((inhibit-read-only t))
1945      (delete-char 1)
1946      (insert ?D)
1947      (forward-line 1)
1948      (bookmark-bmenu-ensure-position))))
1949
1950
1951 (defun bookmark-bmenu-delete-backwards ()
1952   "Mark bookmark on this line to be deleted, then move up one line.
1953 To carry out the deletions that you've marked, use \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-execute-deletions]."
1954   (interactive)
1955   (bookmark-bmenu-delete)
1956   (forward-line -2)
1957   (bookmark-bmenu-ensure-position)
1958   (forward-line 1)
1959   (bookmark-bmenu-ensure-position))
1960
1961
1962 (defun bookmark-bmenu-execute-deletions ()
1963   "Delete bookmarks marked with \\<Buffer-menu-mode-map>\\[Buffer-menu-delete] commands."
1964   (interactive)
1965   (message "Deleting bookmarks...")
1966   (let ((o-point  (point))
1967         (o-str    (save-excursion
1968                     (beginning-of-line)
1969                     (unless (looking-at "^D")
1970                       (buffer-substring
1971                        (point)
1972                        (progn (end-of-line) (point))))))
1973         (o-col     (current-column)))
1974     (goto-char (point-min))
1975     (forward-line 1)
1976     (while (re-search-forward "^D" (point-max) t)
1977       (bookmark-delete (bookmark-bmenu-bookmark) t)) ; pass BATCH arg
1978     (bookmark-bmenu-list)
1979     (if o-str
1980         (progn
1981           (goto-char (point-min))
1982           (search-forward o-str)
1983           (beginning-of-line)
1984           (forward-char o-col))
1985       (goto-char o-point))
1986     (beginning-of-line)
1987     (message "Deleting bookmarks...done")
1988     ))
1989
1990
1991 (defun bookmark-bmenu-rename ()
1992   "Rename bookmark on current line.  Prompts for a new name."
1993   (interactive)
1994   (let ((bmrk (bookmark-bmenu-bookmark))
1995         (thispoint (point)))
1996     (bookmark-rename bmrk)
1997     (goto-char thispoint)))
1998
1999
2000 (defun bookmark-bmenu-locate ()
2001   "Display location of this bookmark.  Displays in the minibuffer."
2002   (interactive)
2003   (let ((bmrk (bookmark-bmenu-bookmark)))
2004     (message "%s" (bookmark-location bmrk))))
2005
2006 (defun bookmark-bmenu-relocate ()
2007   "Change the file path of the bookmark on the current line,
2008   prompting with completion for the new path."
2009   (interactive)
2010   (let ((bmrk (bookmark-bmenu-bookmark))
2011         (thispoint (point)))
2012     (bookmark-relocate bmrk)
2013     (goto-char thispoint)))
2014
2015 ;;; Bookmark-bmenu search
2016
2017 ;; Store keyboard input for incremental search.
2018 (defvar bookmark-search-pattern)
2019
2020 (defun bookmark-read-search-input ()
2021   "Read each keyboard input and add it to `bookmark-search-pattern'."
2022   (let ((prompt       (propertize "Pattern: " 'face 'minibuffer-prompt))
2023         ;; (inhibit-quit t) ; inhibit-quit is evil.  Use it with extreme care!
2024         (tmp-list     ()))
2025     (while
2026         (let ((char (read-key (concat prompt bookmark-search-pattern))))
2027           (case char
2028             ((?\e ?\r) nil) ; RET or ESC break the search loop.
2029             (?\C-g (setq bookmark-quit-flag t) nil)
2030             (?\d (pop tmp-list) t) ; Delete last char of pattern with DEL
2031             (t
2032              (if (characterp char)
2033                  (push char tmp-list)
2034                (setq unread-command-events
2035                      (nconc (mapcar 'identity
2036                                     (this-single-command-raw-keys))
2037                             unread-command-events))
2038                nil))))
2039       (setq bookmark-search-pattern
2040             (apply 'string (reverse tmp-list))))))
2041
2042
2043 (defun bookmark-bmenu-filter-alist-by-regexp (regexp)
2044   "Filter `bookmark-alist' with bookmarks matching REGEXP and rebuild list."
2045   (let ((bookmark-alist
2046          (loop for i in bookmark-alist
2047                when (string-match regexp (car i)) collect i into new
2048                finally return new)))
2049     (bookmark-bmenu-list)))
2050
2051
2052 ;;;###autoload
2053 (defun bookmark-bmenu-search ()
2054   "Incremental search of bookmarks, hiding the non-matches as we go."
2055   (interactive)
2056   (let ((bmk (bookmark-bmenu-bookmark))
2057         (bookmark-search-pattern "")
2058         (timer (run-with-idle-timer
2059                 bookmark-search-delay 'repeat
2060                 #'(lambda ()
2061                     (bookmark-bmenu-filter-alist-by-regexp
2062                      bookmark-search-pattern)))))
2063     (unwind-protect
2064         (bookmark-read-search-input)
2065       (cancel-timer timer)
2066       (message nil)
2067       (when bookmark-quit-flag        ; C-g hit restore menu list.
2068         (bookmark-bmenu-list) (bookmark-bmenu-goto-bookmark bmk))
2069       (setq bookmark-quit-flag nil))))
2070
2071 (defun bookmark-bmenu-goto-bookmark (name)
2072   "Move point to bookmark with name NAME."
2073   (goto-char (point-min))
2074   (while (not (equal name (bookmark-bmenu-bookmark)))
2075     (forward-line 1))
2076   (forward-line 0))
2077
2078
2079 \f
2080 ;;; Menu bar stuff.  Prefix is "bookmark-menu".
2081
2082 (defun bookmark-menu-popup-paned-menu (event name entries)
2083   "Pop up multi-paned menu at EVENT, return string chosen from ENTRIES.
2084 That is, ENTRIES is a list of strings which appear as the choices
2085 in the menu.
2086 The number of panes depends on the number of entries.
2087 The visible entries are truncated to `bookmark-menu-length', but the
2088 strings returned are not."
2089   (let ((f-height (/ (frame-height) 2))
2090         (pane-list nil)
2091         (iter 0))
2092     (while entries
2093       (let (lst
2094             (count 0))
2095         (while (and (< count f-height) entries)
2096           (let ((str (car entries)))
2097             (push (cons
2098                    (if (> (length str) bookmark-menu-length)
2099                        (substring str 0 bookmark-menu-length)
2100                      str)
2101                    str)
2102                   lst)
2103             (setq entries (cdr entries))
2104             (setq count (1+ count))))
2105         (setq iter (1+ iter))
2106         (push (cons
2107                (format "-*- %s (%d) -*-" name iter)
2108                (nreverse lst))
2109               pane-list)))
2110
2111     ;; Popup the menu and return the string.
2112     (x-popup-menu event (cons (concat "-*- " name " -*-")
2113                               (nreverse pane-list)))))
2114
2115
2116 ;; Thanks to Roland McGrath for fixing menubar.el so that the
2117 ;; following works, and for explaining what to do to make it work.
2118
2119 ;; We MUST autoload EACH form used to set up this variable's value, so
2120 ;; that the whole job is done in loaddefs.el.
2121
2122 ;; Emacs menubar stuff.
2123
2124 ;;;###autoload
2125 (defvar menu-bar-bookmark-map
2126   (let ((map (make-sparse-keymap "Bookmark functions")))
2127     (define-key map [load]
2128       `(menu-item ,(purecopy "Load a Bookmark File...") bookmark-load
2129                   :help ,(purecopy "Load bookmarks from a bookmark file)")))
2130     (define-key map [write]
2131       `(menu-item ,(purecopy "Save Bookmarks As...") bookmark-write
2132                   :help ,(purecopy "Write bookmarks to a file (reading the file name with the minibuffer)")))
2133     (define-key map [save]
2134       `(menu-item ,(purecopy "Save Bookmarks") bookmark-save
2135                   :help ,(purecopy "Save currently defined bookmarks")))
2136     (define-key map [edit]
2137       `(menu-item ,(purecopy "Edit Bookmark List") bookmark-bmenu-list
2138                   :help ,(purecopy "Display a list of existing bookmarks")))
2139     (define-key map [delete]
2140       `(menu-item ,(purecopy "Delete Bookmark...") bookmark-delete
2141                   :help ,(purecopy "Delete a bookmark from the bookmark list")))
2142     (define-key map [rename]
2143       `(menu-item ,(purecopy "Rename Bookmark...") bookmark-rename
2144                   :help ,(purecopy "Change the name of a bookmark")))
2145     (define-key map [locate]
2146       `(menu-item ,(purecopy "Insert Location...") bookmark-locate
2147                   :help ,(purecopy "Insert the name of the file associated with a bookmark")))
2148     (define-key map [insert]
2149       `(menu-item ,(purecopy "Insert Contents...") bookmark-insert
2150                   :help ,(purecopy "Insert the text of the file pointed to by a bookmark")))
2151     (define-key map [set]
2152       `(menu-item ,(purecopy "Set Bookmark...") bookmark-set
2153                   :help ,(purecopy "Set a bookmark named inside a file.")))
2154     (define-key map [jump]
2155       `(menu-item ,(purecopy "Jump to Bookmark...") bookmark-jump
2156                   :help ,(purecopy "Jump to a bookmark (a point in some file)")))
2157     map))
2158
2159 ;;;###autoload
2160 (defalias 'menu-bar-bookmark-map menu-bar-bookmark-map)
2161
2162 ;; make bookmarks appear toward the right side of the menu.
2163 (if (boundp 'menu-bar-final-items)
2164     (if menu-bar-final-items
2165         (push 'bookmark menu-bar-final-items))
2166   (setq menu-bar-final-items '(bookmark)))
2167
2168 ;;;; end bookmark menu stuff ;;;;
2169
2170 \f
2171 ;; Load Hook
2172 (defvar bookmark-load-hook nil
2173   "Hook run at the end of loading bookmark.")
2174
2175 ;; Exit Hook, called from kill-emacs-hook
2176 (defvar bookmark-exit-hook nil
2177   "Hook run when Emacs exits.")
2178
2179 (define-obsolete-variable-alias 'bookmark-exit-hooks 'bookmark-exit-hook "22.1")
2180
2181 (defun bookmark-exit-hook-internal ()
2182   "Save bookmark state, if necessary, at Emacs exit time.
2183 This also runs `bookmark-exit-hook'."
2184   (run-hooks 'bookmark-exit-hook)
2185   (and bookmark-alist
2186        (bookmark-time-to-save-p t)
2187        (bookmark-save)))
2188
2189 (add-hook 'kill-emacs-hook 'bookmark-exit-hook-internal)
2190
2191 (defun bookmark-unload-function ()
2192   "Unload the Bookmark library."
2193   (when bookmark-save-flag (bookmark-save))
2194   ;; continue standard unloading
2195   nil)
2196
2197
2198 (run-hooks 'bookmark-load-hook)
2199
2200 (provide 'bookmark)
2201
2202 ;; arch-tag: 139f519a-dd0c-4b8d-8b5d-f9fcf53ca8f6
2203 ;;; bookmark.el ends here