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