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