1 ;;; imenu.el --- framework for mode-specific buffer indexes
3 ;; Copyright (C) 1994, 1995, 1996, 1997, 1998, 2003, 2004
4 ;; Free Software Foundation, Inc.
6 ;; Author: Ake Stenhoff <etxaksf@aom.ericsson.se>
7 ;; Lars Lindberg <lli@sypro.cap.se>
10 ;; Keywords: tools convenience
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software; you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation; either version 2, or (at your option)
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs; see the file COPYING. If not, write to the
26 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
27 ;; Boston, MA 02111-1307, USA.
31 ;; Purpose of this package:
32 ;; To present a framework for mode-specific buffer indexes.
33 ;; A buffer index is an alist of names and buffer positions.
34 ;; For instance all functions in a C-file and their positions.
36 ;; It is documented in the Emacs Lisp manual.
40 ;; A mode-specific function is called to generate the index. It is
41 ;; then presented to the user, who can choose from this index.
43 ;; The package comes with a set of example functions for how to
44 ;; utilize this package.
46 ;; There are *examples* for index gathering functions/regular
47 ;; expressions for C/C++ and Lisp/Emacs Lisp but it is easy to
48 ;; customize for other modes. A function for jumping to the chosen
49 ;; index position is also supplied.
53 ;; [simon] - Simon Leinen simon@lia.di.epfl.ch
54 ;; [dean] - Dean Andrews ada@unison.com
55 ;; [alon] - Alon Albert al@mercury.co.il
56 ;; [greg] - Greg Thompson gregt@porsche.visix.COM
57 ;; [wolfgang] - Wolfgang Bangerth zcg51122@rpool1.rus.uni-stuttgart.de
58 ;; [kai] - Kai Grossjohann grossjoh@linus.informatik.uni-dortmund.de
59 ;; [david] - David M. Smith dsmith@stats.adelaide.edu.au
60 ;; [christian] - Christian Egli Christian.Egli@hcsd.hac.com
61 ;; [karl] - Karl Fogel kfogel@floss.life.uiuc.edu
65 (eval-when-compile (require 'cl
))
67 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
69 ;;; Customizable variables
71 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
74 "Mode-specific buffer indexes."
78 :link
'(custom-manual "(elisp)Imenu"))
80 (defcustom imenu-use-markers t
81 "*Non-nil means use markers instead of integers for Imenu buffer positions.
83 Setting this to nil makes Imenu work a little faster but editing the
84 buffer will make the generated index positions wrong.
86 This might not yet be honored by all index-building functions."
91 (defcustom imenu-max-item-length
60
92 "*If a number, truncate Imenu entries to that length."
93 :type
'(choice integer
94 (const :tag
"Unlimited"))
97 (defcustom imenu-auto-rescan nil
98 "*Non-nil means Imenu should always rescan the buffers."
102 (defcustom imenu-auto-rescan-maxout
60000
103 "*Imenu auto-rescan is disabled in buffers larger than this size (in bytes).
104 This variable is buffer-local."
108 (defvar imenu-always-use-completion-buffer-p nil
)
109 (make-obsolete-variable 'imenu-always-use-completion-buffer-p
110 'imenu-use-popup-menu
"22.1")
112 (defcustom imenu-use-popup-menu
113 (if imenu-always-use-completion-buffer-p
114 (not (eq imenu-always-use-completion-buffer-p
'never
))
116 "Use a popup menu rather than a minibuffer prompt.
117 If nil, always use a minibuffer prompt.
118 If t, always use a popup menu,
119 If `on-mouse' use a popup menu when `imenu' was invoked with the mouse."
120 :type
'(choice (const :tag
"On Mouse" on-mouse
)
121 (const :tag
"Never" nil
)
122 (other :tag
"Always" t
))
125 (defcustom imenu-eager-completion-buffer
126 (not (eq imenu-always-use-completion-buffer-p
'never
))
127 "If non-nil, eagerly popup the completion buffer."
132 (defcustom imenu-after-jump-hook nil
133 "*Hooks called after jumping to a place in the buffer.
135 Useful things to use here include `reposition-window', `recenter', and
136 \(lambda () (recenter 0)) to show at top of screen."
141 (defcustom imenu-sort-function nil
142 "*The function to use for sorting the index mouse-menu.
144 Affects only the mouse index menu.
146 Set this to nil if you don't want any sorting (faster).
147 The items in the menu are then presented in the order they were found
150 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
152 The function should take two arguments and return t if the first
153 element should come before the second. The arguments are cons cells;
154 \(NAME . POSITION). Look at `imenu--sort-by-name' for an example."
155 :type
'(choice (const :tag
"No sorting" nil
)
156 (const :tag
"Sort by name" imenu--sort-by-name
)
157 (function :tag
"Another function"))
160 (defcustom imenu-max-items
25
161 "*Maximum number of elements in a mouse menu for Imenu."
165 ;; No longer used. KFS 2004-10-27
166 ;; (defcustom imenu-scanning-message "Scanning buffer for index (%3d%%)"
167 ;; "*Progress message during the index scanning of the buffer.
168 ;; If non-nil, user gets a message during the scanning of the buffer.
170 ;; Relevant only if the mode-specific function that creates the buffer
171 ;; index use `imenu-progress-message', and not useful if that is fast, in
172 ;; which case you might as well set this to nil."
173 ;; :type '(choice string
174 ;; (const :tag "None" nil))
177 (defcustom imenu-space-replacement
"."
178 "*The replacement string for spaces in index names.
179 Used when presenting the index in a completion buffer to make the
180 names work as tokens."
181 :type
'(choice string
(const nil
))
184 (defcustom imenu-level-separator
":"
185 "*The separator between index names of different levels.
186 Used for making mouse-menu titles and for flattening nested indexes
187 with name concatenation."
192 (defvar imenu-generic-expression nil
193 "The regex pattern to use for creating a buffer index.
195 If non-nil this pattern is passed to `imenu--generic-function' to
196 create a buffer index. Look there for the documentation of this
199 For example, see the value of `fortran-imenu-generic-expression' used by
200 `fortran-mode' with `imenu-syntax-alist' set locally to give the
201 characters which normally have \"symbol\" syntax \"word\" syntax
205 (make-variable-buffer-local 'imenu-generic-expression
)
210 (defvar imenu-create-index-function
'imenu-default-create-index-function
211 "The function to use for creating a buffer index.
213 It should be a function that takes no arguments and returns an index
214 of the current buffer as an alist.
216 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
217 Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
218 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
219 The function `imenu--subalist-p' tests an element and returns t
220 if it is a sub-alist.
222 This function is called within a `save-excursion'.")
224 (make-variable-buffer-local 'imenu-create-index-function
)
227 (defvar imenu-prev-index-position-function
'beginning-of-defun
228 "Function for finding the next index position.
230 If `imenu-create-index-function' is set to
231 `imenu-default-create-index-function', then you must set this variable
232 to a function that will find the next index, looking backwards in the
235 The function should leave point at the place to be connected to the
236 index and it should return nil when it doesn't find another index.")
238 (make-variable-buffer-local 'imenu-prev-index-position-function
)
241 (defvar imenu-extract-index-name-function nil
242 "Function for extracting the index item name, given a position.
244 This function is called after `imenu-prev-index-position-function'
245 finds a position for an index item, with point at that position.
246 It should return the name for that index item.")
248 (make-variable-buffer-local 'imenu-extract-index-name-function
)
251 (defvar imenu-name-lookup-function nil
252 "Function to compare string with index item.
254 This function will be called with two strings, and should return
255 non-nil if they match.
257 If nil, comparison is done with `string='.
258 Set this to some other function for more advanced comparisons,
259 such as \"begins with\" or \"name matches and number of
262 (make-variable-buffer-local 'imenu-name-lookup-function
)
265 (defvar imenu-default-goto-function
'imenu-default-goto-function
266 "The default function called when selecting an Imenu item.
267 The function in this variable is called when selecting a normal index-item.")
269 (make-variable-buffer-local 'imenu-default-goto-function
)
272 (defun imenu--subalist-p (item)
273 (and (consp (cdr item
)) (listp (cadr item
))
274 (not (eq (car (cadr item
)) 'lambda
))))
276 ;; Macro to display a progress message.
277 ;; RELPOS is the relative position to display.
278 ;; If RELPOS is nil, then the relative position in the buffer
280 ;; PREVPOS is the variable in which we store the last position displayed.
281 (defmacro imenu-progress-message
(prevpos &optional relpos reverse
)
283 ;; Made obsolete/empty, as computers are now faster than the eye, and
284 ;; it had problems updating the messages correctly, and could shadow
285 ;; more important messages/prompts in the minibuffer. KFS 2004-10-27.
288 ;; imenu-scanning-message
289 ;; (let ((pos ,(if relpos
291 ;; `(imenu--relative-position ,reverse))))
293 ;; `(> pos (+ 5 ,prevpos)))
295 ;; (message imenu-scanning-message pos)
296 ;; (setq ,prevpos pos)))))
300 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
302 ;;;; Some examples of functions utilizing the framework of this
305 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
307 ;; FIXME: This is the only imenu-example-* definition that's actually used,
308 ;; and it seems to only be used by cperl-mode.el. We should just move it to
309 ;; cperl-mode.el and remove the rest.
310 (defun imenu-example--name-and-position ()
311 "Return the current/previous sexp and its (beginning) location.
315 ;; [ydi] modified for imenu-use-markers
316 (let ((beg (if imenu-use-markers
(point-marker) (point)))
317 (end (progn (forward-sexp) (point))))
318 (cons (buffer-substring beg end
)
325 (defun imenu-example--lisp-extract-index-name ()
326 ;; Example of a candidate for `imenu-extract-index-name-function'.
327 ;; This will generate a flat index of definitions in a lisp file.
329 (and (looking-at "(def")
335 (end (progn (forward-sexp -
1) (point))))
336 (buffer-substring beg end
)))
339 (defun imenu-example--create-lisp-index ()
340 ;; Example of a candidate for `imenu-create-index-function'.
341 ;; It will generate a nested index of definitions.
342 (let ((index-alist '())
343 (index-var-alist '())
344 (index-type-alist '())
345 (index-unknown-alist '())
347 (goto-char (point-max))
348 (imenu-progress-message prev-pos
0)
349 ;; Search for the function
350 (while (beginning-of-defun)
351 (imenu-progress-message prev-pos nil t
)
353 (and (looking-at "(def")
357 ((looking-at "def\\(var\\|const\\)")
359 (push (imenu-example--name-and-position)
361 ((looking-at "def\\(un\\|subst\\|macro\\|advice\\)")
363 (push (imenu-example--name-and-position)
365 ((looking-at "def\\(type\\|struct\\|class\\|ine-condition\\)")
367 (if (= (char-after (1- (point))) ?\
))
372 (push (imenu-example--name-and-position)
376 (push (imenu-example--name-and-position)
377 index-unknown-alist
)))))))
378 (imenu-progress-message prev-pos
100)
380 (push (cons "Variables" index-var-alist
)
382 (and index-type-alist
383 (push (cons "Types" index-type-alist
)
385 (and index-unknown-alist
386 (push (cons "Syntax-unknown" index-unknown-alist
)
390 ;; Regular expression to find C functions
391 (defvar imenu-example--function-name-regexp-c
393 "^[a-zA-Z0-9]+[ \t]?" ; type specs; there can be no
394 "\\([a-zA-Z0-9_*]+[ \t]+\\)?" ; more than 3 tokens, right?
395 "\\([a-zA-Z0-9_*]+[ \t]+\\)?"
396 "\\([*&]+[ \t]*\\)?" ; pointer
397 "\\([a-zA-Z0-9_*]+\\)[ \t]*(" ; name
400 (defun imenu-example--create-c-index (&optional regexp
)
401 (let ((index-alist '())
403 (goto-char (point-min))
404 (imenu-progress-message prev-pos
0)
405 ;; Search for the function
407 (while (re-search-forward
408 (or regexp imenu-example--function-name-regexp-c
)
410 (imenu-progress-message prev-pos
)
413 (goto-char (scan-sexps (point) 1))
414 (setq char
(following-char)))
415 ;; Skip this function name if it is a prototype declaration.
416 (if (not (eq char ?\
;))
417 (push (imenu-example--name-and-position) index-alist
))))
418 (imenu-progress-message prev-pos
100)
419 (nreverse index-alist
)))
422 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
424 ;;; Internal variables
426 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
428 ;; The item to use in the index for rescanning the buffer.
429 (defconst imenu--rescan-item
'("*Rescan*" . -
99))
431 ;; The latest buffer index.
433 (defvar imenu--index-alist nil
434 "The buffer index computed for this buffer in Imenu.
435 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
436 Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
437 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).")
439 (make-variable-buffer-local 'imenu--index-alist
)
441 (defvar imenu--last-menubar-index-alist nil
442 "The latest buffer index used to update the menu bar menu.")
444 (make-variable-buffer-local 'imenu--last-menubar-index-alist
)
446 ;; History list for 'jump-to-function-in-buffer'.
447 ;; Making this buffer local caused it not to work!
448 (defvar imenu--history-list nil
)
450 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
452 ;;; Internal support functions
454 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
458 ;;; Sorts the items depending on their index name.
459 ;;; An item looks like (NAME . POSITION).
461 (defun imenu--sort-by-name (item1 item2
)
462 (string-lessp (car item1
) (car item2
)))
464 (defun imenu--sort-by-position (item1 item2
)
465 (< (cdr item1
) (cdr item2
)))
467 (defun imenu--relative-position (&optional reverse
)
468 ;; Support function to calculate relative position in buffer
469 ;; Beginning of buffer is 0 and end of buffer is 100
470 ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
472 (total (buffer-size)))
473 (and reverse
(setq pos
(- total pos
)))
475 ;; Avoid overflow from multiplying by 100!
476 (/ (1- pos
) (max (/ total
100) 1))
477 (/ (* 100 (1- pos
)) (max total
1)))))
479 ;; Split LIST into sublists of max length N.
480 ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
481 (defun imenu--split (list n
)
487 (push (pop remain
) sublist
)
490 ;; We have finished a sublist
491 (progn (push (nreverse sublist
) result
)
493 (setq sublist
'()))))
494 ;; There might be a sublist (if the length of LIST mod n is != 0)
495 ;; that has to be added to the result list.
497 (push (nreverse sublist
) result
))
500 ;;; Split the alist MENULIST into a nested alist, if it is long enough.
501 ;;; In any case, add TITLE to the front of the alist.
502 (defun imenu--split-menu (menulist title
)
503 (let (keep-at-top tail
)
504 (if (memq imenu--rescan-item menulist
)
505 (setq keep-at-top
(cons imenu--rescan-item nil
)
506 menulist
(delq imenu--rescan-item menulist
)))
509 (when (imenu--subalist-p item
)
510 (push item keep-at-top
)
511 (setq menulist
(delq item menulist
))))
512 (if imenu-sort-function
513 (setq menulist
(sort (copy-sequence menulist
) imenu-sort-function
)))
514 (if (> (length menulist
) imenu-max-items
)
518 (cons (format "From: %s" (caar menu
)) menu
))
519 (imenu--split menulist imenu-max-items
))))
521 (nconc (nreverse keep-at-top
) menulist
))))
523 ;;; Split up each long alist that are nested within ALIST
524 ;;; into nested alists.
525 (defun imenu--split-submenus (alist)
531 (imenu--split-menu (cdr elt
) (car elt
))
535 ;;; Truncate all strings in MENULIST to imenu-max-item-length
536 (defun imenu--truncate-items (menulist)
541 (imenu--truncate-items (cdr item
)))
542 ;; truncate if necessary
543 ((and (numberp imenu-max-item-length
)
544 (> (length (car item
)) imenu-max-item-length
))
545 (setcar item
(substring (car item
) 0 imenu-max-item-length
))))))
549 (defun imenu--make-index-alist (&optional noerror
)
550 "Create an index-alist for the definitions in the current buffer.
552 Report an error if the list is empty unless NOERROR is supplied and
555 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
556 Special elements look like (INDEX-NAME FUNCTION ARGUMENTS...).
557 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
558 The function `imenu--subalist-p' tests an element and returns t
559 if it is a sub-alist.
561 There is one simple element with negative POSITION; that's intended
562 as a way for the user to ask to recalculate the buffer's index alist."
563 (or (and imenu--index-alist
564 (or (not imenu-auto-rescan
)
565 (and imenu-auto-rescan
566 (> (buffer-size) imenu-auto-rescan-maxout
))))
567 ;; Get the index; truncate if necessary
569 (setq imenu--index-alist
573 (funcall imenu-create-index-function
))))
574 (imenu--truncate-items imenu--index-alist
)))
575 (or imenu--index-alist noerror
576 (error "No items suitable for an index found in this buffer"))
577 (or imenu--index-alist
578 (setq imenu--index-alist
(list nil
)))
579 ;; Add a rescan option to the index.
580 (cons imenu--rescan-item imenu--index-alist
))
582 ;;; Find all markers in alist and makes
583 ;;; them point nowhere.
584 ;;; The top-level call uses nil as the argument;
585 ;;; non-nil arguments are in recursivecalls.
586 (defvar imenu--cleanup-seen
)
588 (defun imenu--cleanup (&optional alist
)
589 ;; If alist is provided use that list.
590 ;; If not, empty the table of lists already seen
591 ;; and use imenu--index-alist.
593 (setq imenu--cleanup-seen
(cons alist imenu--cleanup-seen
))
594 (setq alist imenu--index-alist imenu--cleanup-seen
(list alist
)))
600 ((markerp (cdr item
))
601 (set-marker (cdr item
) nil
))
602 ;; Don't process one alist twice.
603 ((memq (cdr item
) imenu--cleanup-seen
))
604 ((imenu--subalist-p item
)
605 (imenu--cleanup (cdr item
)))))
609 (defun imenu--create-keymap (title alist
&optional cmd
)
613 (list* (car item
) (car item
)
615 ((imenu--subalist-p item
)
616 (imenu--create-keymap (car item
) (cdr item
) cmd
))
618 `(lambda () (interactive)
619 ,(if cmd
`(,cmd
',item
) (list 'quote item
)))))))
622 (defun imenu--in-alist (str alist
)
623 "Check whether the string STR is contained in multi-level ALIST."
624 (let (elt head tail res
)
627 (setq elt
(car alist
)
631 ;; A nested ALIST element looks like
632 ;; (INDEX-NAME (INDEX-NAME . INDEX-POSITION) ...)
633 ;; while a bottom-level element looks like
634 ;; (INDEX-NAME . INDEX-POSITION)
635 ;; We are only interested in the bottom-level elements, so we need to
636 ;; recurse if TAIL is a list.
638 (if (setq res
(imenu--in-alist str tail
))
640 ((if imenu-name-lookup-function
641 (funcall imenu-name-lookup-function str head
)
643 (setq alist nil res elt
))))
646 (defvar imenu-syntax-alist nil
647 "Alist of syntax table modifiers to use while in `imenu--generic-function'.
649 The car of the assocs may be either a character or a string and the
650 cdr is a syntax description appropriate for `modify-syntax-entry'. For
651 a string, all the characters in the string get the specified syntax.
653 This is typically used to give word syntax to characters which
654 normally have symbol syntax to simplify `imenu-expression'
655 and speed-up matching.")
657 (make-variable-buffer-local 'imenu-syntax-alist
)
659 (defun imenu-default-create-index-function ()
660 "*Wrapper for index searching functions.
662 Moves point to end of buffer and then repeatedly calls
663 `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
664 Their results are gathered into an index alist."
665 ;; These should really be done by setting imenu-create-index-function
666 ;; in these major modes. But save that change for later.
667 (cond ((and imenu-prev-index-position-function
668 imenu-extract-index-name-function
)
669 (let ((index-alist '())
671 (goto-char (point-max))
672 (imenu-progress-message prev-pos
0 t
)
673 ;; Search for the function
674 (while (funcall imenu-prev-index-position-function
)
675 (imenu-progress-message prev-pos nil t
)
677 (setq name
(funcall imenu-extract-index-name-function
)))
679 ;; [ydi] updated for imenu-use-markers
680 (push (cons name
(if imenu-use-markers
(point-marker) (point)))
682 (imenu-progress-message prev-pos
100 t
)
684 ;; Use generic expression if possible.
685 ((and imenu-generic-expression
)
686 (imenu--generic-function imenu-generic-expression
))
688 (error "This buffer cannot use `imenu-default-create-index-function'"))))
690 ;; Not used and would require cl at run time
691 ;; (defun imenu--flatten-index-alist (index-alist &optional concat-names prefix)
692 ;; ;; Takes a nested INDEX-ALIST and returns a flat index alist.
693 ;; ;; If optional CONCAT-NAMES is non-nil, then a nested index has its
694 ;; ;; name and a space concatenated to the names of the children.
695 ;; ;; Third argument PREFIX is for internal use only.
698 ;; (let* ((name (car item))
700 ;; (new-prefix (and concat-names
702 ;; (concat prefix imenu-level-separator name)
705 ;; ((or (markerp pos) (numberp pos))
706 ;; (list (cons new-prefix pos)))
708 ;; (imenu--flatten-index-alist pos new-prefix)))))
712 ;;; Generic index gathering function.
715 (defvar imenu-case-fold-search t
716 "Defines whether `imenu--generic-function' should fold case when matching.
718 This variable should be set (only) by initialization code
719 for modes which use `imenu--generic-function'. If it is not set, but
720 `font-lock-defaults' is set, then font-lock's setting is used.")
722 (make-variable-buffer-local 'imenu-case-fold-search
)
724 ;; This function can be called with quitting disabled,
725 ;; so it needs to be careful never to loop!
726 (defun imenu--generic-function (patterns)
727 "Return an index of the current buffer as an alist.
729 PATTERNS is an alist with elements that look like this:
730 (MENU-TITLE REGEXP INDEX)
732 (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)
733 with zero or more ARGUMENTS. The former format creates a simple
734 element in the index alist when it matches; the latter creates a
735 special element of the form (NAME POSITION-MARKER FUNCTION
736 ARGUMENTS...) with FUNCTION and ARGUMENTS copied from
737 `imenu-generic-expression'.
739 MENU-TITLE is a string used as the title for the submenu or nil
740 if the entries are not nested.
742 REGEXP is a regexp that should match a construct in the buffer
743 that is to be displayed in the menu; i.e., function or variable
744 definitions, etc. It contains a substring which is the name to
745 appear in the menu. See the info section on Regexps for more
746 information. REGEXP may also be a function, called without
747 arguments. It is expected to search backwards. It shall return
748 true and set `match-data' iff it finds another element.
750 INDEX points to the substring in REGEXP that contains the
751 name (of the function, variable or type) that is to appear in the
754 The variable `imenu-case-fold-search' determines whether or not the
755 regexp matches are case sensitive, and `imenu-syntax-alist' can be
756 used to alter the syntax table for the search.
758 See `lisp-imenu-generic-expression' for an example of PATTERNS.
760 Returns an index of the current buffer as an alist. The elements in
762 (INDEX-NAME . INDEX-POSITION)
764 (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)
765 They may also be nested index alists like:
766 (INDEX-NAME . INDEX-ALIST)
767 depending on PATTERNS."
769 (let ((index-alist (list 'dummy
))
771 (case-fold-search (if (or (local-variable-p 'imenu-case-fold-search
)
772 (not (local-variable-p 'font-lock-defaults
)))
773 imenu-case-fold-search
774 (nth 2 font-lock-defaults
)))
775 (old-table (syntax-table))
776 (table (copy-syntax-table (syntax-table)))
777 (slist imenu-syntax-alist
))
778 ;; Modify the syntax table used while matching regexps.
780 ;; The character(s) to modify may be a single char or a string.
781 (if (numberp (car syn
))
782 (modify-syntax-entry (car syn
) (cdr syn
) table
)
784 (modify-syntax-entry c
(cdr syn
) table
))
786 (goto-char (point-max))
787 (imenu-progress-message prev-pos
0 t
)
788 (unwind-protect ; for syntax table
790 (set-syntax-table table
)
792 ;; map over the elements of imenu-generic-expression
793 ;; (typically functions, variables ...)
794 (dolist (pat patterns
)
795 (let ((menu-title (car pat
))
798 (function (nth 3 pat
))
799 (rest (nthcdr 4 pat
))
801 ;; Go backwards for convenience of adding items in order.
802 (goto-char (point-max))
803 (while (and (if (functionp regexp
)
805 (re-search-backward regexp nil t
))
806 ;; Exit the loop if we get an empty match,
807 ;; because it means a bad regexp was specified.
808 (not (= (match-beginning 0) (match-end 0))))
810 ;; Record the start of the line in which the match starts.
811 ;; That's the official position of this definition.
812 (goto-char (match-beginning index
))
815 (imenu-progress-message prev-pos nil t
)
816 ;; Add this sort of submenu only when we've found an
817 ;; item for it, avoiding empty, duff menus.
818 (unless (assoc menu-title index-alist
)
819 (push (list menu-title
) index-alist
))
820 (if imenu-use-markers
821 (setq beg
(copy-marker beg
)))
824 (nconc (list (match-string-no-properties index
)
827 (cons (match-string-no-properties index
)
829 ;; This is the desired submenu,
830 ;; starting with its title (or nil).
831 (menu (assoc menu-title index-alist
)))
832 ;; Insert the item unless it is already present.
833 (unless (member item
(cdr menu
))
835 (cons item
(cdr menu
)))))
836 ;; Go to the start of the match, to make sure we
837 ;; keep making progress backwards.
839 (set-syntax-table old-table
)))
840 (imenu-progress-message prev-pos
100 t
)
841 ;; Sort each submenu by position.
842 ;; This is in case one submenu gets items from two different regexps.
843 (dolist (item index-alist
)
845 (setcdr item
(sort (cdr item
) 'imenu--sort-by-position
))))
846 (let ((main-element (assq nil index-alist
)))
847 (nconc (delq main-element
(delq 'dummy index-alist
))
848 (cdr main-element
)))))
850 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
852 ;;; The main functions for this package!
854 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
856 ;; See also info-lookup-find-item
857 (defun imenu-find-default (guess completions
)
858 "Fuzzily find an item based on GUESS inside the alist COMPLETIONS."
860 (let ((case-fold-search t
))
861 (if (assoc guess completions
) guess
862 (dolist (re (list (concat "\\`" (regexp-quote guess
) "\\'")
863 (concat "\\`" (regexp-quote guess
))
864 (concat (regexp-quote guess
) "\\'")
865 (regexp-quote guess
)))
866 (dolist (x completions
)
867 (if (string-match re
(car x
)) (throw 'found
(car x
)))))))))
869 (defun imenu--completion-buffer (index-alist &optional prompt
)
870 "Let the user select from INDEX-ALIST in a completion buffer with PROMPT.
872 Return one of the entries in index-alist or nil."
873 ;; Create a list for this buffer only when needed.
874 (let ((name (thing-at-point 'symbol
))
876 (prepared-index-alist
877 (if (not imenu-space-replacement
) index-alist
880 (cons (subst-char-in-string ?\s
(aref imenu-space-replacement
0)
885 (setq name
(or (imenu-find-default name prepared-index-alist
) name
)))
887 ((and name
(imenu--in-alist name prepared-index-alist
))
888 (setq prompt
(format "Index item (default %s): " name
)))
889 (t (setq prompt
"Index item: ")))
890 (let ((minibuffer-setup-hook minibuffer-setup-hook
))
891 ;; Display the completion buffer.
892 (if (not imenu-eager-completion-buffer
)
893 (add-hook 'minibuffer-setup-hook
'minibuffer-completion-help
))
894 (setq name
(completing-read prompt
896 nil t nil
'imenu--history-list name
)))
899 (setq choice
(assoc name prepared-index-alist
))
900 (if (imenu--subalist-p choice
)
901 (imenu--completion-buffer (cdr choice
) prompt
)
904 (defun imenu--mouse-menu (index-alist event
&optional title
)
905 "Let the user select from a buffer index from a mouse menu.
907 INDEX-ALIST is the buffer index and EVENT is a mouse event.
909 Returns t for rescan and otherwise an element or subelement of INDEX-ALIST."
910 (setq index-alist
(imenu--split-submenus index-alist
))
911 (let* ((menu (imenu--split-menu index-alist
(or title
(buffer-name))))
912 (map (imenu--create-keymap (car menu
)
913 (cdr (if (< 1 (length (cdr menu
)))
915 (car (cdr menu
)))))))
916 (popup-menu map event
)))
918 (defun imenu-choose-buffer-index (&optional prompt alist
)
919 "Let the user select from a buffer index and return the chosen index.
921 If the user originally activated this function with the mouse, a mouse
922 menu is used. Otherwise a completion buffer is used and the user is
923 prompted with PROMPT.
925 If you call this function with index alist ALIST, then it lets the user
928 With no index alist ALIST, it calls `imenu--make-index-alist' to
929 create the index alist.
931 If `imenu-use-popup-menu' is non-nil, then the
932 completion buffer is always used, no matter if the mouse was used or
935 The returned value is of the form (INDEX-NAME . INDEX-POSITION)."
937 (mouse-triggered (listp last-nonmenu-event
))
939 ;; If selected by mouse, see to that the window where the mouse is
940 ;; really is selected.
942 (not (equal last-nonmenu-event
'(menu-bar)))
943 (let ((window (posn-window (event-start last-nonmenu-event
))))
944 (or (framep window
) (null window
) (select-window window
))))
945 ;; Create a list for this buffer only when needed.
947 (setq index-alist
(if alist alist
(imenu--make-index-alist)))
949 (if (and imenu-use-popup-menu
950 (or (eq imenu-use-popup-menu t
) mouse-triggered
))
951 (imenu--mouse-menu index-alist last-nonmenu-event
)
952 (imenu--completion-buffer index-alist prompt
)))
953 (and (equal result imenu--rescan-item
)
955 (setq result t imenu--index-alist nil
)))
959 (defun imenu-add-to-menubar (name)
960 "Add an `imenu' entry to the menu bar for the current buffer.
961 NAME is a string used to name the menu bar item.
962 See the command `imenu' for more information."
963 (interactive "sImenu menu item name: ")
964 (if (or (and imenu-prev-index-position-function
965 imenu-extract-index-name-function
)
966 imenu-generic-expression
967 (not (eq imenu-create-index-function
968 'imenu-default-create-index-function
)))
969 (let ((newmap (make-sparse-keymap)))
970 (set-keymap-parent newmap
(current-local-map))
971 (setq imenu--last-menubar-index-alist nil
)
972 (define-key newmap
[menu-bar index
]
973 `(menu-item ,name
,(make-sparse-keymap "Imenu")))
974 (use-local-map newmap
)
975 (add-hook 'menu-bar-update-hook
'imenu-update-menubar
))
976 (error "The mode `%s' does not support Imenu" mode-name
)))
979 (defun imenu-add-menubar-index ()
980 "Add an Imenu \"Index\" entry on the menu bar for the current buffer.
982 A trivial interface to `imenu-add-to-menubar' suitable for use in a hook."
984 (imenu-add-to-menubar "Index"))
986 (defvar imenu-buffer-menubar nil
)
988 (defvar imenu-menubar-modified-tick
0
989 "The value of (buffer-modified-tick) as of last call to `imenu-update-menubar'.")
990 (make-variable-buffer-local 'imenu-menubar-modified-tick
)
992 (defun imenu-update-menubar ()
993 (when (and (current-local-map)
994 (keymapp (lookup-key (current-local-map) [menu-bar index
]))
995 (not (eq (buffer-modified-tick)
996 imenu-menubar-modified-tick
)))
997 (setq imenu-menubar-modified-tick
(buffer-modified-tick))
998 (let ((index-alist (imenu--make-index-alist t
)))
999 ;; Don't bother updating if the index-alist has not changed
1000 ;; since the last time we did it.
1001 (unless (equal index-alist imenu--last-menubar-index-alist
)
1002 (let (menu menu1 old
)
1003 (setq imenu--last-menubar-index-alist index-alist
)
1004 (setq index-alist
(imenu--split-submenus index-alist
))
1005 (setq menu
(imenu--split-menu index-alist
1007 (setq menu1
(imenu--create-keymap (car menu
)
1008 (cdr (if (< 1 (length (cdr menu
)))
1011 'imenu--menubar-select
))
1012 (setq old
(lookup-key (current-local-map) [menu-bar index
]))
1013 (setcdr old
(cdr menu1
)))))))
1015 (defun imenu--menubar-select (item)
1016 "Use Imenu to select the function or variable named in this menu ITEM."
1017 (if (equal item imenu--rescan-item
)
1020 ;; Make sure imenu-update-menubar redoes everything.
1021 (setq imenu-menubar-modified-tick -
1)
1022 (setq imenu--index-alist nil
)
1023 (setq imenu--last-menubar-index-alist nil
)
1024 (imenu-update-menubar)
1029 (defun imenu-default-goto-function (name position
&optional rest
)
1030 "Move to the given position.
1032 NAME is ignored. POSITION is where to move. REST is also ignored.
1033 The ignored args just make this function have the same interface as a
1034 function placed in a special index-item."
1035 (if (or (< position
(point-min))
1036 (> position
(point-max)))
1037 ;; widen if outside narrowing
1039 (goto-char position
))
1042 (defun imenu (index-item)
1043 "Jump to a place in the buffer chosen using a buffer menu or mouse menu.
1044 INDEX-ITEM specifies the position. See `imenu-choose-buffer-index'
1045 for more information."
1046 (interactive (list (imenu-choose-buffer-index)))
1047 ;; Convert a string to an alist element.
1048 (if (stringp index-item
)
1049 (setq index-item
(assoc index-item
(imenu--make-index-alist))))
1052 (let* ((is-special-item (listp (cdr index-item
)))
1055 (nth 2 index-item
) imenu-default-goto-function
))
1056 (position (if is-special-item
1057 (cadr index-item
) (cdr index-item
)))
1058 (rest (if is-special-item
(cddr index-item
))))
1059 (apply function
(car index-item
) position rest
))
1060 (run-hooks 'imenu-after-jump-hook
)))
1063 '("^No items suitable for an index found in this buffer$"
1064 "^This buffer cannot use `imenu-default-create-index-function'$"
1065 "^The mode `.*' does not support Imenu$"))
1066 (add-to-list 'debug-ignored-errors mess
))
1070 ;; arch-tag: 98a2f5f5-4b91-4704-b18c-3aacf77d77a7
1071 ;;; imenu.el ends here