1 ;;; reftex-sel.el --- the selection modes for RefTeX
3 ;; Copyright (C) 1997-2016 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <dominik@science.uva.nl>
6 ;; Maintainer: auctex-devel@gnu.org
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
27 (eval-when-compile (require 'cl))
31 ;; Common bindings in reftex-select-label-mode-map
32 ;; and reftex-select-bib-mode-map.
33 (defvar reftex-select-shared-map
34 (let ((map (make-sparse-keymap)))
35 (substitute-key-definition
36 'next-line 'reftex-select-next map global-map)
37 (substitute-key-definition
38 'previous-line 'reftex-select-previous map global-map)
39 (substitute-key-definition
40 'keyboard-quit 'reftex-select-keyboard-quit map global-map)
41 (substitute-key-definition
42 'newline 'reftex-select-accept map global-map)
45 '((" " . reftex-select-callback)
46 ("n" . reftex-select-next)
47 ([(down)] . reftex-select-next)
48 ("p" . reftex-select-previous)
49 ([(up)] . reftex-select-previous)
50 ("f" . reftex-select-toggle-follow)
51 ("\C-m" . reftex-select-accept)
52 ([(return)] . reftex-select-accept)
53 ("q" . reftex-select-quit)
54 ("." . reftex-select-show-insertion-point)
55 ("?" . reftex-select-help))
56 do (define-key map (car x) (cdr x)))
58 ;; The mouse-2 binding
59 (if (featurep 'xemacs)
60 (define-key map [(button2)] 'reftex-select-mouse-accept)
61 (define-key map [(mouse-2)] 'reftex-select-mouse-accept)
62 (define-key map [follow-link] 'mouse-face))
66 (loop for key across "0123456789" do
67 (define-key map (vector (list key)) 'digit-argument))
68 (define-key map "-" 'negative-argument)
71 (define-obsolete-variable-alias
72 'reftex-select-label-map 'reftex-select-label-mode-map "24.1")
73 (defvar reftex-select-label-mode-map
74 (let ((map (make-sparse-keymap)))
75 (set-keymap-parent map reftex-select-shared-map)
77 (loop for key across "aAcgFlrRstx#%" do
78 (define-key map (vector (list key))
80 "Press `?' during selection to find out about this key."
81 '(interactive) (list 'throw '(quote myexit) key))))
84 '(("b" . reftex-select-jump-to-previous)
85 ("z" . reftex-select-jump)
86 ("v" . reftex-select-cycle-ref-style-forward)
87 ("V" . reftex-select-cycle-ref-style-backward)
88 ("m" . reftex-select-mark)
89 ("u" . reftex-select-unmark)
90 ("," . reftex-select-mark-comma)
91 ("-" . reftex-select-mark-to)
92 ("+" . reftex-select-mark-and)
93 ([(tab)] . reftex-select-read-label)
94 ("\C-i" . reftex-select-read-label)
95 ("\C-c\C-n" . reftex-select-next-heading)
96 ("\C-c\C-p" . reftex-select-previous-heading))
98 (define-key map (car x) (cdr x)))
101 "Keymap used for *RefTeX Select* buffer, when selecting a label.
102 This keymap can be used to configure the label selection process which is
103 started with the command \\[reftex-reference].")
106 (define-derived-mode reftex-select-label-mode special-mode "LSelect"
107 "Major mode for selecting a label in a LaTeX document.
108 This buffer was created with RefTeX.
109 It only has a meaningful keymap when you are in the middle of a
111 To select a label, move the cursor to it and press RET.
112 Press `?' for a summary of important key bindings.
114 During a selection process, these are the local bindings.
116 \\{reftex-select-label-mode-map}"
117 (when (featurep 'xemacs)
118 ;; XEmacs needs the call to make-local-hook
119 (make-local-hook 'pre-command-hook)
120 (make-local-hook 'post-command-hook))
121 (set (make-local-variable 'reftex-select-marked) nil)
122 (when (syntax-table-p reftex-latex-syntax-table)
123 (set-syntax-table reftex-latex-syntax-table))
124 ;; We do not set a local map - reftex-select-item does this.
127 (define-obsolete-variable-alias
128 'reftex-select-bib-map 'reftex-select-bib-mode-map "24.1")
129 (defvar reftex-select-bib-mode-map
130 (let ((map (make-sparse-keymap)))
131 (set-keymap-parent map reftex-select-shared-map)
133 (loop for key across "grRaAeE" do
134 (define-key map (vector (list key))
136 "Press `?' during selection to find out about this key."
137 '(interactive) (list 'throw '(quote myexit) key))))
140 '(("\C-i" . reftex-select-read-cite)
141 ([(tab)] . reftex-select-read-cite)
142 ("m" . reftex-select-mark)
143 ("u" . reftex-select-unmark))
144 do (define-key map (car x) (cdr x)))
147 "Keymap used for *RefTeX Select* buffer, when selecting a BibTeX entry.
148 This keymap can be used to configure the BibTeX selection process which is
149 started with the command \\[reftex-citation].")
152 (define-derived-mode reftex-select-bib-mode special-mode "BSelect"
153 "Major mode for selecting a citation key in a LaTeX document.
154 This buffer was created with RefTeX.
155 It only has a meaningful keymap when you are in the middle of a
157 In order to select a citation, move the cursor to it and press RET.
158 Press `?' for a summary of important key bindings.
160 During a selection process, these are the local bindings.
162 \\{reftex-select-label-mode-map}"
163 (when (featurep 'xemacs)
164 ;; XEmacs needs the call to make-local-hook
165 (make-local-hook 'pre-command-hook)
166 (make-local-hook 'post-command-hook))
167 (set (make-local-variable 'reftex-select-marked) nil)
168 ;; We do not set a local map - reftex-select-item does this.
171 ;; (defun reftex-get-offset (buf here-am-I &optional typekey toc index file)
172 ;; ;; Find the correct offset data, like insert-docstruct would, but faster.
173 ;; ;; Buffer BUF knows the correct docstruct to use.
174 ;; ;; Basically this finds the first docstruct entry after HERE-I-AM which
175 ;; ;; is of allowed type. The optional arguments specify what is allowed.
177 ;; (with-current-buffer buf
178 ;; (reftex-access-scan-info)
179 ;; (let* ((rest (memq here-am-I (symbol-value reftex-docstruct-symbol)))
181 ;; (while (setq entry (pop rest))
182 ;; (if (or (and typekey
183 ;; (stringp (car entry))
184 ;; (or (equal typekey " ")
185 ;; (equal typekey (nth 1 entry))))
186 ;; (and toc (eq (car entry) 'toc))
187 ;; (and index (eq (car entry) 'index))
189 ;; (memq (car entry) '(bof eof file-error))))
190 ;; (throw 'exit entry)))
194 (defun reftex-get-offset (buf here-am-I &optional typekey toc index file)
195 ;; Find the correct offset data, like insert-docstruct would, but faster.
196 ;; Buffer BUF knows the correct docstruct to use.
197 ;; Basically this finds the first docstruct entry before HERE-I-AM which
198 ;; is of allowed type. The optional arguments specify what is allowed.
200 (with-current-buffer buf
201 (reftex-access-scan-info)
202 (let* ((rest (symbol-value reftex-docstruct-symbol))
204 (while (setq entry (pop rest))
206 (stringp (car entry))
207 (or (equal typekey " ")
208 (equal typekey (nth 1 entry))))
209 (and toc (eq (car entry) 'toc))
210 (and index (eq (car entry) 'index))
212 (memq (car entry) '(bof eof file-error))))
213 (setq lastentry entry))
214 (if (eq entry here-am-I)
215 (throw 'exit (or lastentry entry))))
219 (defun reftex-insert-docstruct
220 (buf toc labels index-entries files context counter show-commented
221 here-I-am xr-prefix toc-buffer)
222 ;; Insert an excerpt of the docstruct list.
223 ;; Return the data property of the entry corresponding to HERE-I-AM.
224 ;; BUF is the buffer which has the correct docstruct-symbol.
225 ;; LABELS non-nil means to include labels into the list.
226 ;; When a string, indicates the label type to include
227 ;; FILES non-nil means to display file boundaries.
228 ;; CONTEXT non-nil means to include label context.
229 ;; COUNTER means to count the labels.
230 ;; SHOW-COMMENTED means to include also labels which are commented out.
231 ;; HERE-I-AM is a member of the docstruct list. The function will return
232 ;; a used member near to this one, as a possible starting point.
233 ;; XR-PREFIX is the prefix to put in front of labels.
234 ;; TOC-BUFFER means this is to fill the toc buffer.
235 (let* ((font (reftex-use-fonts))
241 (if toc (make-string (* 7 reftex-level-indent) ?\ ) "")))
244 (if toc (make-string (* 7 reftex-level-indent) ?\ ) "")))
246 (if (memq reftex-highlight-selection '(mouse both))
247 reftex-mouse-selected-face
249 (label-face reftex-label-face)
250 (index-face reftex-index-face)
251 all cell text label typekey note comment master-dir-re
252 prev-inserted offset from to index-tag docstruct-symbol)
254 ;; Pop to buffer buf to get the correct buffer-local variables
255 (with-current-buffer buf
257 ;; Ensure access to scanning info
258 (reftex-access-scan-info)
260 (setq docstruct-symbol reftex-docstruct-symbol
261 all (symbol-value reftex-docstruct-symbol)
262 reftex-active-toc nil
264 (concat "\\`" (regexp-quote
265 (file-name-directory (reftex-TeX-master-file))))))
267 (set (make-local-variable 'reftex-docstruct-symbol) docstruct-symbol)
268 (set (make-local-variable 'reftex-prefix)
269 (cdr (assoc labels reftex-typekey-to-prefix-alist)))
270 (if (equal reftex-prefix " ") (setq reftex-prefix nil))
272 ;; Walk the docstruct and insert the appropriate stuff
273 (while (setq cell (pop all))
280 ((memq (car cell) '(bib thebib label-numbers appendix
281 master-dir bibview-cache is-multi xr xr-doc)))
282 ;; These are currently ignored
284 ((memq (car cell) '(bof eof file-error))
285 ;; Beginning or end of a file
287 (setq prev-inserted cell)
288 ; (if (eq offset 'attention) (setq offset cell))
290 " File " (if (string-match master-dir-re (nth 1 cell))
291 (substring (nth 1 cell) (match-end 0))
293 (cond ((eq (car cell) 'bof) " starts here\n")
294 ((eq (car cell) 'eof) " ends here\n")
295 ((eq (car cell) 'file-error) " was not found\n")))
298 (put-text-property from to
299 'font-lock-face reftex-file-boundary-face))
302 (put-text-property from (1- to)
303 'mouse-face mouse-face))
304 (put-text-property from to :data cell))))
306 ((eq (car cell) 'toc)
307 ;; a table of contents entry
309 (<= (nth 5 cell) reftex-toc-max-level))
310 (setq prev-inserted cell)
311 ; (if (eq offset 'attention) (setq offset cell))
312 (setq reftex-active-toc cell)
313 (insert (concat toc-indent (nth 2 cell) "\n"))
316 (put-text-property from to
317 'font-lock-face reftex-section-heading-face))
320 (put-text-property from (1- to)
321 'mouse-face mouse-face))
322 (put-text-property from to :data cell))
325 ((stringp (car cell))
327 (when (null (nth 2 cell))
328 ;; No context yet. Quick update.
329 (setcdr cell (cdr (reftex-label-info-update cell)))
330 (put docstruct-symbol 'modified t))
332 (setq label (car cell)
340 (string= typekey labels)
341 (string= labels " "))
342 (or show-commented (null comment)))
344 ;; Yes we want this one
346 (setq prev-inserted cell)
347 ; (if (eq offset 'attention) (setq offset cell))
349 (setq label (concat xr-prefix label))
350 (when comment (setq label (concat "% " label)))
351 (insert label-indent label)
355 (- (point) (length label)) to
356 'font-lock-face (if comment
357 'font-lock-comment-face
361 (insert (if counter (format " (%d) " cnt) "")
362 (if comment " LABEL IS COMMENTED OUT " "")
363 (if (stringp note) (concat " " note) "")
368 (insert context-indent text "\n")
370 (put-text-property from to :data cell)
372 (put-text-property from (1- to)
373 'mouse-face mouse-face))
376 ((eq (car cell) 'index)
378 (when (and index-entries
379 (or (eq t index-entries)
380 (string= index-entries (nth 1 cell))))
381 (setq prev-inserted cell)
382 ; (if (eq offset 'attention) (setq offset cell))
383 (setq index-tag (format "<%s>" (nth 1 cell)))
385 (put-text-property 0 (length index-tag)
386 'font-lock-face reftex-index-tag-face index-tag))
387 (insert label-indent index-tag " " (nth 7 cell))
392 (- (point) (length (nth 7 cell))) to
393 'font-lock-face index-face)
399 (insert context-indent (nth 2 cell) "\n")
401 (put-text-property from to :data cell)
403 (put-text-property from (1- to)
404 'mouse-face mouse-face))
407 (if (eq cell here-I-am)
408 (setq offset 'attention))
409 (if (and prev-inserted (eq offset 'attention))
410 (setq offset prev-inserted))
413 (when (reftex-refontify)
414 ;; we need to fontify the buffer
415 (reftex-fontify-select-label-buffer buf))
416 (run-hooks 'reftex-display-copied-context-hook)
420 (defun reftex-find-start-point (fallback &rest locations)
421 ;; Set point to the first available LOCATION. When a LOCATION is a list,
422 ;; search for such a :data text property. When it is an integer,
423 ;; use is as line number. FALLBACK is a buffer position used if everything
426 (goto-char (point-min))
429 (setq loc (pop locations))
433 (setq pos (text-property-any (point-min) (point-max) :data loc))
438 (when (<= loc (count-lines (point-min) (point-max)))
439 (goto-char (point-min))
440 (forward-line (1- loc))
442 (goto-char fallback))))
444 (defvar reftex-last-data nil)
445 (defvar reftex-last-line nil)
446 (defvar reftex-select-marked nil)
449 (defun reftex-select-item (reftex-select-prompt help-string keymap
452 ;; Select an item, using REFTEX-SELECT-PROMPT.
453 ;; The function returns a key indicating an exit status, along with a
454 ;; data structure indicating which item was selected.
455 ;; HELP-STRING contains help. KEYMAP is a keymap with the available
456 ;; selection commands.
457 ;; OFFSET can be a label list item which will be selected at start.
458 ;; When it is t, point will start out at the beginning of the buffer.
459 ;; Any other value will cause restart where last selection left off.
460 ;; When CALL-BACK is given, it is a function which is called with the index
462 ;; CB-FLAG is the initial value of that flag.
463 (let (ev reftex-select-data last-data (selection-buffer (current-buffer)))
465 (setq reftex-select-marked nil)
469 (save-window-excursion
470 (setq truncate-lines t)
472 ;; Find a good starting point
473 (reftex-find-start-point
474 (point-min) offset reftex-last-data reftex-last-line)
475 (beginning-of-line 1)
476 (set (make-local-variable 'reftex-last-follow-point) (point))
480 (use-local-map keymap)
481 (add-hook 'pre-command-hook 'reftex-select-pre-command-hook nil t)
482 (add-hook 'post-command-hook 'reftex-select-post-command-hook nil t)
483 (princ reftex-select-prompt)
484 (set-marker reftex-recursive-edit-marker (point))
485 ;; XEmacs does not run post-command-hook here
486 (and (featurep 'xemacs) (run-hooks 'post-command-hook))
489 (set-marker reftex-recursive-edit-marker nil)
490 (with-current-buffer selection-buffer
492 (remove-hook 'pre-command-hook 'reftex-select-pre-command-hook t)
493 (remove-hook 'post-command-hook
494 'reftex-select-post-command-hook t))
495 ;; Kill the mark overlays
496 (mapc (lambda (c) (reftex-delete-overlay (nth 1 c)))
497 reftex-select-marked)))))
499 (set (make-local-variable 'reftex-last-line)
500 (+ (count-lines (point-min) (point)) (if (bolp) 1 0)))
501 (set (make-local-variable 'reftex-last-data) last-data)
502 (reftex-kill-buffer "*RefTeX Help*")
503 (setq reftex-callback-fwd (not reftex-callback-fwd)) ;; ;-)))
505 (list ev reftex-select-data last-data)))
507 ;; The following variables are all bound dynamically in `reftex-select-item'.
508 ;; The defvars are here only to silence the byte compiler.
512 (defvar reftex-select-data)
513 (defvar reftex-select-prompt)
517 (defvar reftex-refstyle)
519 ;; The selection commands
521 (defun reftex-select-pre-command-hook ()
522 (reftex-unhighlight 1)
523 (reftex-unhighlight 0))
525 (defun reftex-select-post-command-hook ()
527 (setq reftex-select-data (get-text-property (point) :data))
528 (setq last-data (or reftex-select-data last-data))
530 (when (and reftex-select-data cb-flag
531 (not (equal reftex-last-follow-point (point))))
532 (setq reftex-last-follow-point (point))
533 (funcall call-back reftex-select-data reftex-callback-fwd
534 (not reftex-revisit-to-follow)))
535 (if reftex-select-data
536 (setq b (or (previous-single-property-change
539 e (or (next-single-property-change
542 (setq b (point) e (point)))
543 (and (memq reftex-highlight-selection '(cursor both))
544 (reftex-highlight 1 b e))
545 (if (or (not (pos-visible-in-window-p b))
546 (not (pos-visible-in-window-p e)))
548 (unless (current-message)
549 (princ reftex-select-prompt))))
551 (defun reftex-select-next (&optional arg)
552 "Move to next selectable item."
554 (setq reftex-callback-fwd t)
555 (or (eobp) (forward-char 1))
556 (re-search-forward "^[^. \t\n\r]" nil t arg)
557 (beginning-of-line 1))
558 (defun reftex-select-previous (&optional arg)
559 "Move to previous selectable item."
561 (setq reftex-callback-fwd nil)
562 (re-search-backward "^[^. \t\n\r]" nil t arg))
563 (defun reftex-select-jump (arg)
564 "Jump to a specific section. E.g. '3 z' jumps to section 3.
565 Useful for large TOC's."
567 (goto-char (point-min))
569 (concat "^ *" (number-to-string (if (numberp arg) arg 1)) " ")
572 (defun reftex-select-next-heading (&optional arg)
573 "Move to next table of contents line."
576 (re-search-forward "^ " nil t arg)
578 (defun reftex-select-previous-heading (&optional arg)
579 "Move to previous table of contents line."
581 (re-search-backward "^ " nil t arg))
582 (defun reftex-select-quit ()
583 "Abort selection process."
586 (defun reftex-select-keyboard-quit ()
587 "Abort selection process."
590 (defun reftex-select-jump-to-previous ()
591 "Jump back to where previous selection process left off."
595 ((and (local-variable-p 'reftex-last-data (current-buffer))
597 (setq pos (text-property-any (point-min) (point-max)
598 :data reftex-last-data)))
600 ((and (local-variable-p 'reftex-last-line (current-buffer))
601 (integerp reftex-last-line))
602 (goto-char (point-min))
603 (forward-line (1- reftex-last-line)))
605 (defun reftex-select-toggle-follow ()
606 "Toggle follow mode: Other window follows with full context."
608 (setq reftex-last-follow-point -1)
609 (setq cb-flag (not cb-flag)))
611 (defun reftex-select-cycle-ref-style-internal (&optional reverse)
612 "Cycle through macros used for referencing.
613 Cycle in reverse order if optional argument REVERSE is non-nil."
615 (dolist (style (reftex-ref-style-list))
616 (mapc (lambda (x) (add-to-list 'list (car x) t))
617 (nth 2 (assoc style reftex-ref-style-alist))))
619 (setq list (reverse list)))
620 (setq reftex-refstyle (or (cadr (member reftex-refstyle list)) (car list))))
621 (force-mode-line-update))
623 (defun reftex-select-cycle-ref-style-forward ()
624 "Cycle forward through macros used for referencing."
626 (reftex-select-cycle-ref-style-internal))
628 (defun reftex-select-cycle-ref-style-backward ()
629 "Cycle backward through macros used for referencing."
631 (reftex-select-cycle-ref-style-internal t))
633 (defun reftex-select-show-insertion-point ()
634 "Show the point from where selection was started in another window."
636 (let ((this-window (selected-window)))
639 (switch-to-buffer-other-window
640 (marker-buffer reftex-select-return-marker))
641 (goto-char (marker-position reftex-select-return-marker))
643 (select-window this-window))))
644 (defun reftex-select-callback ()
645 "Show full context in another window."
647 (if reftex-select-data (funcall call-back reftex-select-data reftex-callback-fwd nil) (ding)))
648 (defun reftex-select-accept ()
649 "Accept the currently selected item."
651 (throw 'myexit 'return))
652 (defun reftex-select-mouse-accept (ev)
653 "Accept the item at the mouse click."
656 (setq reftex-select-data (get-text-property (point) :data))
657 (setq last-data (or reftex-select-data last-data))
658 (throw 'myexit 'return))
659 (defun reftex-select-read-label ()
660 "Use minibuffer to read a label to reference, with completion."
662 (let ((label (completing-read
663 "Label: " (symbol-value reftex-docstruct-symbol)
664 nil nil reftex-prefix)))
665 (unless (or (equal label "") (equal label reftex-prefix))
666 (throw 'myexit label))))
667 (defun reftex-select-read-cite ()
668 "Use minibuffer to read a citation key with completion."
670 (let* ((key (completing-read "Citation key: " found-list))
671 (entry (assoc key found-list)))
673 ((or (null key) (equal key "")))
675 (setq reftex-select-data entry)
676 (setq last-data reftex-select-data)
677 (throw 'myexit 'return))
678 (t (throw 'myexit key)))))
680 (defun reftex-select-mark (&optional separator)
683 (let* ((data (get-text-property (point) :data))
685 (or data (error "No entry to mark at point"))
686 (if (assq data reftex-select-marked)
687 (error "Entry is already marked"))
688 (setq boe (or (previous-single-property-change (1+ (point)) :data)
690 eoe (or (next-single-property-change (point) :data) (point-max)))
691 (setq ovl (reftex-make-overlay boe eoe))
692 (push (list data ovl separator) reftex-select-marked)
693 (reftex-overlay-put ovl 'font-lock-face reftex-select-mark-face)
694 (reftex-overlay-put ovl 'before-string
696 (format "*%c%d* " separator
697 (length reftex-select-marked))
698 (format "*%d* " (length reftex-select-marked))))
699 (message "Entry has mark no. %d" (length reftex-select-marked))))
701 (defun reftex-select-mark-comma ()
702 "Mark the entry and store the `comma' separator."
704 (reftex-select-mark ?,))
705 (defun reftex-select-mark-to ()
706 "Mark the entry and store the `to' separator."
708 (reftex-select-mark ?-))
709 (defun reftex-select-mark-and ()
710 "Mark the entry and store `and' to separator."
712 (reftex-select-mark ?+))
714 (defun reftex-select-unmark ()
717 (let* ((data (get-text-property (point) :data))
718 (cell (assq data reftex-select-marked))
723 (error "No marked entry at point"))
724 (and ovl (reftex-delete-overlay ovl))
725 (setq reftex-select-marked (delq cell reftex-select-marked))
726 (setq cnt (1+ (length reftex-select-marked)))
729 (reftex-overlay-put (nth 1 c) 'before-string
731 (format "*%c%d* " sep (decf cnt))
732 (format "*%d* " (decf cnt)))))
733 reftex-select-marked)
734 (message "Entry no longer marked")))
736 (defun reftex-select-help ()
737 "Display a summary of the special key bindings."
739 (with-output-to-temp-buffer "*RefTeX Help*"
741 (reftex-enlarge-to-fit "*RefTeX Help*" t))
743 (provide 'reftex-sel)
745 ;;; reftex-sel.el ends here
748 ;; generated-autoload-file: "reftex.el"