| blob | 65213ef1b28a7098ff4a880418a94cad0d67622e |
1 ;;; imenu.el --- framework for mode-specific buffer indexes
3 ;; Copyright (C) 1994, 1995, 1996, 1997, 1998, 2001, 2002, 2003, 2004,
4 ;; 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
6 ;; Author: Ake Stenhoff <etxaksf@aom.ericsson.se>
7 ;; Lars Lindberg <lli@sypro.cap.se>
8 ;; Maintainer: FSF
9 ;; Created: 8 Feb 1994
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 3 of the License, or
17 ;; (at your option) any later version.
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. If not, see <http://www.gnu.org/licenses/>.
27 ;;; Commentary:
29 ;; Purpose of this package:
30 ;; To present a framework for mode-specific buffer indexes.
31 ;; A buffer index is an alist of names and buffer positions.
32 ;; For instance all functions in a C-file and their positions.
33 ;;
34 ;; It is documented in the Emacs Lisp manual.
35 ;;
36 ;; How it works:
38 ;; A mode-specific function is called to generate the index. It is
39 ;; then presented to the user, who can choose from this index.
40 ;;
41 ;; The package comes with a set of example functions for how to
42 ;; utilize this package.
44 ;; There are *examples* for index gathering functions/regular
45 ;; expressions for C/C++ and Lisp/Emacs Lisp but it is easy to
46 ;; customize for other modes. A function for jumping to the chosen
47 ;; index position is also supplied.
49 ;;; History:
50 ;; Thanks go to
51 ;; [simon] - Simon Leinen simon@lia.di.epfl.ch
52 ;; [dean] - Dean Andrews ada@unison.com
53 ;; [alon] - Alon Albert al@mercury.co.il
54 ;; [greg] - Greg Thompson gregt@porsche.visix.COM
55 ;; [wolfgang] - Wolfgang Bangerth zcg51122@rpool1.rus.uni-stuttgart.de
56 ;; [kai] - Kai Grossjohann grossjoh@linus.informatik.uni-dortmund.de
57 ;; [david] - David M. Smith dsmith@stats.adelaide.edu.au
58 ;; [christian] - Christian Egli Christian.Egli@hcsd.hac.com
59 ;; [karl] - Karl Fogel kfogel@floss.life.uiuc.edu
61 ;;; Code:
65 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
66 ;;;
67 ;;; Customizable variables
68 ;;;
69 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
72 "Mode-specific buffer indexes."
79 "Non-nil means use markers instead of integers for Imenu buffer positions.
81 Setting this to nil makes Imenu work a little faster but editing the
82 buffer will make the generated index positions wrong.
84 This might not yet be honored by all index-building functions."
90 "If a number, truncate Imenu entries to that length."
96 "Non-nil means Imenu should always rescan the buffers."
101 "Imenu auto-rescan is disabled in buffers larger than this size (in bytes).
102 This variable is buffer-local."
114 "Use a popup menu rather than a minibuffer prompt.
115 If nil, always use a minibuffer prompt.
116 If t, always use a popup menu,
117 If `on-mouse' use a popup menu when `imenu' was invoked with the mouse."
125 "If non-nil, eagerly popup the completion buffer."
131 "Hooks called after jumping to a place in the buffer.
133 Useful things to use here include `reposition-window', `recenter', and
134 \(lambda () (recenter 0)) to show at top of screen."
138 ;;;###autoload
140 "The function to use for sorting the index mouse-menu.
142 Affects only the mouse index menu.
144 Set this to nil if you don't want any sorting (faster).
145 The items in the menu are then presented in the order they were found
146 in the buffer.
148 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
150 The function should take two arguments and return t if the first
151 element should come before the second. The arguments are cons cells;
152 \(NAME . POSITION). Look at `imenu--sort-by-name' for an example."
159 "Maximum number of elements in a mouse menu for Imenu."
163 ;; No longer used. KFS 2004-10-27
164 ;; (defcustom imenu-scanning-message "Scanning buffer for index (%3d%%)"
165 ;; "*Progress message during the index scanning of the buffer.
166 ;; If non-nil, user gets a message during the scanning of the buffer.
167 ;;
168 ;; Relevant only if the mode-specific function that creates the buffer
169 ;; index use `imenu-progress-message', and not useful if that is fast, in
170 ;; which case you might as well set this to nil."
171 ;; :type '(choice string
172 ;; (const :tag "None" nil))
173 ;; :group 'imenu)
176 "The replacement string for spaces in index names.
177 Used when presenting the index in a completion buffer to make the
178 names work as tokens."
183 "The separator between index names of different levels.
184 Used for making mouse-menu titles and for flattening nested indexes
185 with name concatenation."
189 ;;;###autoload
191 "The regex pattern to use for creating a buffer index.
193 If non-nil this pattern is passed to `imenu--generic-function' to
194 create a buffer index. Look there for the documentation of this
195 pattern's structure.
197 For example, see the value of `fortran-imenu-generic-expression' used by
198 `fortran-mode' with `imenu-syntax-alist' set locally to give the
202 ;;;###autoload
205 ;;;; Hooks
207 ;;;###autoload
209 "The function to use for creating an index alist of the current buffer.
211 It should be a function that takes no arguments and returns
212 an index alist of the current buffer. The function is
213 called within a `save-excursion'.
216 ;;;###autoload
219 ;;;###autoload
221 "Function for finding the next index position.
223 If `imenu-create-index-function' is set to
224 `imenu-default-create-index-function', then you must set this variable
225 to a function that will find the next index, looking backwards in the
226 file.
228 The function should leave point at the place to be connected to the
230 ;;;###autoload
233 ;;;###autoload
235 "Function for extracting the index item name, given a position.
237 This function is called after `imenu-prev-index-position-function'
238 finds a position for an index item, with point at that position.
240 ;;;###autoload
243 ;;;###autoload
245 "Function to compare string with index item.
247 This function will be called with two strings, and should return
248 non-nil if they match.
250 If nil, comparison is done with `string='.
251 Set this to some other function for more advanced comparisons,
254 ;;;###autoload
257 ;;;###autoload
259 "The default function called when selecting an Imenu item.
261 ;;;###autoload
269 ;; Macro to display a progress message.
270 ;; RELPOS is the relative position to display.
271 ;; If RELPOS is nil, then the relative position in the buffer
272 ;; is calculated.
273 ;; PREVPOS is the variable in which we store the last position displayed.
276 ;; Made obsolete/empty, as computers are now faster than the eye, and
277 ;; it had problems updating the messages correctly, and could shadow
278 ;; more important messages/prompts in the minibuffer. KFS 2004-10-27.
280 ;; `(and
281 ;; imenu-scanning-message
282 ;; (let ((pos ,(if relpos
283 ;; relpos
284 ;; `(imenu--relative-position ,reverse))))
285 ;; (if ,(if relpos t
286 ;; `(> pos (+ 5 ,prevpos)))
287 ;; (progn
288 ;; (message imenu-scanning-message pos)
289 ;; (setq ,prevpos pos)))))
290 )
293 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
294 ;;;;
295 ;;;; Some examples of functions utilizing the framework of this
296 ;;;; package.
297 ;;;;
298 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
300 ;; FIXME: This is the only imenu-example-* definition that's actually used,
301 ;; and it seems to only be used by cperl-mode.el. We should just move it to
302 ;; cperl-mode.el and remove the rest.
304 "Return the current/previous sexp and its (beginning) location.
305 Don't move point."
308 ;; [ydi] modified for imenu-use-markers
312 beg))))
314 ;;;
315 ;;; Lisp
316 ;;;
319 ;; Example of a candidate for `imenu-extract-index-name-function'.
320 ;; This will generate a flat index of definitions in a lisp file.
333 ;; Example of a candidate for `imenu-create-index-function'.
334 ;; It will generate a nested index of definitions.
339 prev-pos)
342 ;; Search for the function
353 index-var-alist))
357 index-alist))
366 index-type-alist))
370 index-unknown-alist)))))))
374 index-alist))
377 index-alist))
380 index-alist))
381 index-alist))
383 ;; Regular expression to find C functions
391 ))
395 prev-pos char)
398 ;; Search for the function
402 nil t)
408 ;; Skip this function name if it is a prototype declaration.
415 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
416 ;;;
417 ;;; Internal variables
418 ;;;
419 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
421 ;; The item to use in the index for rescanning the buffer.
424 ;; The latest buffer index.
425 ;; Buffer local.
427 "The buffer index alist computed for this buffer in Imenu.
429 Simple elements in the alist look like (INDEX-NAME . POSITION).
430 POSITION is the buffer position of the item; to go to the item
431 is simply to move point to that position.
433 Special elements look like (INDEX-NAME POSITION FUNCTION ARGUMENTS...).
435 to INDEX-NAME, POSITION, and the ARGUMENTS.
437 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
438 The function `imenu--subalist-p' tests an element and returns t
439 if it is a sub-alist.
441 There is one simple element with negative POSITION; selecting that
451 ;; History list for 'jump-to-function-in-buffer'.
452 ;; Making this buffer local caused it not to work!
455 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
456 ;;;
457 ;;; Internal support functions
458 ;;;
459 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
461 ;;;
462 ;;; Sort function
463 ;;; Sorts the items depending on their index name.
464 ;;; An item looks like (NAME . POSITION).
465 ;;;
473 ;; Support function to calculate relative position in buffer
474 ;; Beginning of buffer is 0 and end of buffer is 100
475 ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
480 ;; Avoid overflow from multiplying by 100!
484 ;; Split LIST into sublists of max length N.
485 ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
486 ;;
487 ;; The returned list DOES NOT share structure with LIST.
497 ;; We have finished a sublist
501 ;; There might be a sublist (if the length of LIST mod n is != 0)
502 ;; that has to be added to the result list.
507 ;;; Split the alist MENULIST into a nested alist, if it is long enough.
508 ;;; In any case, add TITLE to the front of the alist.
509 ;;; If IMENU--RESCAN-ITEM is present in MENULIST, it is moved to the
510 ;;; beginning of the returned alist.
511 ;;;
512 ;;; The returned alist DOES NOT share structure with MENULIST.
515 keep-at-top tail)
535 ;;; Split up each long alist that are nested within ALIST
536 ;;; into nested alists.
537 ;;;
538 ;;; Return a split and sorted copy of ALIST. The returned alist DOES
539 ;;; NOT share structure with ALIST.
547 elt)))
548 alist))
550 ;;; Truncate all strings in MENULIST to imenu-max-item-length
557 ;; truncate if necessary
561 menulist))
565 "Create an index alist for the definitions in the current buffer.
566 This works by using the hook function `imenu-create-index-function'.
567 Report an error if the list is empty unless NOERROR is supplied and
568 non-nil.
570 See `imenu--index-alist' for the format of the index alist."
575 ;; Get the index; truncate if necessary
587 ;; Add a rescan option to the index.
590 ;;; Find all markers in alist and makes
591 ;;; them point nowhere.
592 ;;; The top-level call uses nil as the argument;
593 ;;; non-nil arguments are in recursivecalls.
597 ;; If alist is provided use that list.
598 ;; If not, empty the table of lists already seen
599 ;; and use imenu--index-alist.
610 ;; Don't process one alist twice.
614 alist)
615 t))
628 alist)))
631 "Check whether the string STR is contained in multi-level ALIST."
639 ;; A nested ALIST element looks like
640 ;; (INDEX-NAME (INDEX-NAME . INDEX-POSITION) ...)
641 ;; while a bottom-level element looks like
642 ;; (INDEX-NAME . INDEX-POSITION)
643 ;; We are only interested in the bottom-level elements, so we need to
644 ;; recurse if TAIL is a list.
652 res))
655 "Alist of syntax table modifiers to use while in `imenu--generic-function'.
657 The car of the assocs may be either a character or a string and the
658 cdr is a syntax description appropriate for `modify-syntax-entry'. For
659 a string, all the characters in the string get the specified syntax.
661 This is typically used to give word syntax to characters which
662 normally have symbol syntax to simplify `imenu-expression'
664 ;;;###autoload
668 "Default function to create an index alist of the current buffer.
670 The most general method is to move point to end of buffer, then repeatedly call
671 `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
672 All the results returned by the latter are gathered into an index alist.
673 This method is used if those two variables are non-nil.
675 The alternate method, which is the one most often used, is to call
676 `imenu--generic-function' with `imenu-generic-expression' as argument."
677 ;; These should really be done by setting imenu-create-index-function
678 ;; in these major modes. But save that change for later.
680 imenu-extract-index-name-function)
682 prev-pos name)
685 ;; Search for the function
691 ;; [ydi] updated for imenu-use-markers
693 index-alist)))
695 index-alist))
696 ;; Use generic expression if possible.
702 ;;;
703 ;;; Generic index gathering function.
704 ;;;
707 "Defines whether `imenu--generic-function' should fold case when matching.
709 This variable should be set (only) by initialization code
710 for modes which use `imenu--generic-function'. If it is not set, but
712 ;;;###autoload
715 ;; This function can be called with quitting disabled,
716 ;; so it needs to be careful never to loop!
718 "Return an index alist of the current buffer based on PATTERNS.
720 PATTERNS is an alist with elements that look like this:
721 (MENU-TITLE REGEXP INDEX)
722 or like this:
723 (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)
724 with zero or more ARGUMENTS. The former format creates a simple
725 element in the index alist when it matches; the latter creates a
726 special element of the form (INDEX-NAME POSITION-MARKER FUNCTION
727 ARGUMENTS...) with FUNCTION and ARGUMENTS copied from PATTERNS.
729 MENU-TITLE is a string used as the title for the submenu or nil
730 if the entries are not nested.
732 REGEXP is a regexp that should match a construct in the buffer
733 that is to be displayed in the menu; i.e., function or variable
734 definitions, etc. It contains a substring which is the name to
735 appear in the menu. See the info section on Regexps for more
736 information. REGEXP may also be a function, called without
737 arguments. It is expected to search backwards. It shall return
738 true and set `match-data' if it finds another element.
740 INDEX points to the substring in REGEXP that contains the
741 name (of the function, variable or type) that is to appear in the
742 menu.
744 The variable `imenu-case-fold-search' determines whether or not the
745 regexp matches are case sensitive, and `imenu-syntax-alist' can be
746 used to alter the syntax table for the search.
748 See `lisp-imenu-generic-expression' for an example of PATTERNS.
750 Returns an index of the current buffer as an alist. The elements in
751 the alist look like:
752 (INDEX-NAME . INDEX-POSITION)
753 or like:
754 (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)
755 They may also be nested index alists like:
756 (INDEX-NAME . INDEX-ALIST)
757 depending on PATTERNS."
760 prev-pos
763 imenu-case-fold-search
768 ;; Modify the syntax table used while matching regexps.
770 ;; The character(s) to modify may be a single char or a string.
782 ;; map over the elements of imenu-generic-expression
783 ;; (typically functions, variables ...)
790 start beg)
791 ;; Go backwards for convenience of adding items in order.
796 ;; Exit the loop if we get an empty match,
797 ;; because it means a bad regexp was specified.
800 ;; Record the start of the line in which the match starts.
801 ;; That's the official position of this definition.
806 ;; Add this sort of submenu only when we've found an
807 ;; item for it, avoiding empty, duff menus.
815 beg function)
816 rest)
818 beg)))
819 ;; This is the desired submenu,
820 ;; starting with its title (or nil).
822 ;; Insert the item unless it is already present.
826 ;; Go to the start of the match, to make sure we
827 ;; keep making progress backwards.
831 ;; Sort each submenu by position.
832 ;; This is in case one submenu gets items from two different regexps.
840 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
841 ;;;
842 ;;; The main functions for this package!
843 ;;;
844 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
846 ;; See also info-lookup-find-item
848 "Fuzzily find an item based on GUESS inside the alist COMPLETIONS."
860 "Let the user select from INDEX-ALIST in a completion buffer with PROMPT.
862 Return one of the entries in index-alist or nil."
863 ;; Create a list for this buffer only when needed.
865 choice
873 index-alist))))
881 ;; Display the completion buffer.
885 prepared-index-alist
892 choice))))
895 "Let the user select from a buffer index from a mouse menu.
897 INDEX-ALIST is the buffer index and EVENT is a mouse event.
899 Returns t for rescan and otherwise an element or subelement of INDEX-ALIST."
904 menu
909 "Let the user select from a buffer index and return the chosen index.
911 If the user originally activated this function with the mouse, a mouse
912 menu is used. Otherwise a completion buffer is used and the user is
913 prompted with PROMPT.
915 If you call this function with index alist ALIST, then it lets the user
916 select from ALIST.
918 With no index alist ALIST, it calls `imenu--make-index-alist' to
919 create the index alist.
921 If `imenu-use-popup-menu' is nil, then the completion buffer
922 is always used, no matter if the mouse was used or not.
924 The returned value is of the form (INDEX-NAME . INDEX-POSITION)."
928 ;; If selected by mouse, see to that the window where the mouse is
929 ;; really is selected.
934 ;; Create a list for this buffer only when needed.
945 result))
947 ;;;###autoload
949 "Add an `imenu' entry to the menu bar for the current buffer.
950 NAME is a string used to name the menu bar item.
951 See the command `imenu' for more information."
954 imenu-extract-index-name-function)
955 imenu-generic-expression
968 ;;;###autoload
972 A trivial interface to `imenu-add-to-menubar' suitable for use in a hook."
979 "The value of (buffer-chars-modified-tick) as of the last call
989 ;; Don't bother updating if the index-alist has not changed
990 ;; since the last time we did it.
999 menu
1006 "Use Imenu to select the function or variable named in this menu ITEM."
1010 ;; Make sure imenu-update-menubar redoes everything.
1015 t)
1017 nil))
1020 "Move to the given position.
1022 NAME is ignored. POSITION is where to move. REST is also ignored.
1023 The ignored args just make this function have the same interface as a
1024 function placed in a special index-item."
1027 ;; widen if outside narrowing
1031 ;;;###autoload
1033 "Jump to a place in the buffer chosen using a buffer menu or mouse menu.
1034 INDEX-ITEM specifies the position. See `imenu-choose-buffer-index'
1035 for more information."
1037 ;; Convert a string to an alist element.
1054 "^This buffer cannot use `imenu-default-create-index-function'$"
1060 ;; arch-tag: 98a2f5f5-4b91-4704-b18c-3aacf77d77a7
1061 ;;; imenu.el ends here