1 ;;; imenu.el --- Framework for mode-specific buffer indexes.
3 ;; Copyright (C) 1994 Free Software Foundation, Inc.
5 ;; Author: Ake Stenhoff <etxaksf@aom.ericsson.se>
6 ;; Lars Lindberg <lli@sypro.cap.se>
11 ;; This program is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; This program is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with this program; if not, write to the Free Software
23 ;; Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27 ;; Purpose of this package:
29 ;; Installation instructions
31 ;; Usage instructions:
35 ;; Purpose of this package:
36 ;; To present a framework for mode-specific buffer indexes.
37 ;; A buffer index is an alist of names and buffer positions.
38 ;; For instance all functions in a C-file and their positions.
42 ;; A mode-specific function is called to generate the index. It is
43 ;; then presented to the user, who can choose from this index.
45 ;; The package comes with a set of example functions for how to
46 ;; utilize this package.
48 ;; There are *examples* for index gathering functions for C/C++ and
49 ;; Lisp/Emacs Lisp but it is easy to customize for other modes. A
50 ;; function for jumping to the chosen index position is also
54 ;; Put this file in your load-path and insert the following in .emacs
56 ;; (autoload 'imenu-choose-buffer-index "imenu" "Menu of buffer index." t)
57 ;; (autoload 'goto-index-pos "imenu" "Goto buffer index position." t)
58 ;; (define-key global-map "\C-cj" 'goto-index-pos) ;; Or some other key
59 ;; (cond (window-system
60 ;; (define-key global-map [S-down-mouse-3] 'goto-index-pos)))
61 ;; Also run the 'add-hook' examples at the bottom of imenu.el.
64 ;; v1.7 Apr 12 1994 Ake Stenhoff
65 ;; Changed doc strings refering to symbols.
66 ;; Require 'cl' when compiling only.
67 ;; Only uses 'cl' macros.
68 ;; v1.6 Feb 28 1994 Ake Stenhoff
69 ;; Added alist as an optional argument to
70 ;; 'imenu-choose-buffer-index'.
72 ;; v1.5 Feb 25 1994 Ake Stenhoff
73 ;; Added code to parse DEFSTRUCT, DEFCLASS, DEFTYPE,
74 ;; DEFINE-CONDITION in the lisp example function.
76 ;; v1.4 Feb 18 1994 Ake Stenhoff
77 ;; Added 'imenu-create-submenu-name' for creating a submenu name.
78 ;; This is for getting a general look of submenu names.
79 ;; Added variable 'imenu-submenu-name-format' used by
80 ;; 'imenu-create-submenu-name'.
81 ;; v1.3 Feb 17 1994 Lars Lindberg
82 ;; Added 'imenu--flatten-index-alist' for flatten nexted index
84 ;; New examples for lisp mode that utilizes the features better.
85 ;; Added the variable 'imenu-space-replacement'.
86 ;; The completion-buffer version of the index menu now replaces
87 ;; spaces in the index-names to make tokens of them.
88 ;; v1.2 Feb 14 1994 Ake Stenhoff & Lars Lindberg
89 ;; Now handles nested index lists.
90 ;; v1.1 Feb 9 1994 Ake Stenhoff & Lars Lindberg
91 ;; Better comments (?).
92 ;; v1.0 Feb 8 1994 Ake Stenhoff & Lars Lindberg
93 ;; Based on func-menu.el 3.5.
96 ;; [simon] - Simon Leinen simon@lia.di.epfl.ch
97 ;; [dean] - Dean Andrews ada@unison.com
101 (eval-when-compile (require 'cl))
103 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
105 ;;; Customizable variables
107 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
109 (defvar imenu-always-use-completion-buffer-p nil
110 "*Set this to non-nil for displaying the index in a completion buffer.
112 Non-nil means always display the index in a completion buffer.
113 Nil means display the index as a mouse menu when the mouse was
114 used to trigger `goto-index-pos'.")
116 (defvar imenu-sort-function nil
117 "*The function to use for sorting the index mouse-menu.
119 Affects only the mouse index menu.
121 Set this to nil if you don't want any sorting (faster).
122 The items in the menu are then presented in the order they were found
125 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
127 The function should take two arguments and return T if the first
128 element should come before the second. The arguments are cons cells;
129 (NAME . POSITION). Look at `imenu--sort-by-name' for an example.")
131 (defvar imenu-max-items 25
132 "*Maximum number of elements in an index mouse-menu.")
134 (defvar imenu-scanning-message "Scanning buffer for index. (%3d%%)"
135 "*Progress message during the index scanning of the buffer.
136 If non NIL, user gets a message during the scanning of the buffer
138 Relevant only if the mode-specific function that creates the buffer
139 index use `imenu-progress-message'.")
141 (defvar imenu-space-replacement "^"
142 "*The replacement string for spaces in index names.
143 Used when presenting the index in a completion-buffer to make the
144 names work as tokens.")
146 (defvar imenu-level-separator ":"
147 "*The separator between index names of different levels.
148 Used for making mouse-menu titles and for flattening nested indexes
149 with name concatenation.")
151 (defvar imenu-submenu-name-format "%s..."
152 "*The format for making a submenu name.")
156 (defvar imenu-create-index-function 'imenu-default-create-index-function
157 "The function to use for creating a buffer index.
159 It should be a function that takes no arguments and returns an index
160 of the current buffer as an alist. The elements in the alist look
161 like: (INDEX-NAME . INDEX-POSITION). You may also nest index list like
162 (INDEX-NAME . INDEX-ALIST).
164 This function is called within a `save-excursion'.
166 The variable is buffer-local.")
167 (make-variable-buffer-local 'imenu-create-index-function)
169 (defvar prev-index-position-function 'beginning-of-defun
170 "Function for finding the next index position.
172 If `imenu-create-index-function' is set to
173 `imenu-default-create-index-function', then you must set this variable
174 to a function that will find the next index, looking backwards in the
177 The function should leave point at the place to be connected to the
178 index and it should return nil when it doesn't find another index. ")
179 (make-variable-buffer-local 'prev-index-position-function)
181 (defvar extract-index-name-function nil
182 "Function for extracting the index name.
184 This function is called after the function pointed out by
185 `prev-index-position-function'.")
186 (make-variable-buffer-local 'extract-index-name-function)
188 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
190 ;;; Internal variables
192 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
194 ;; The item to use in the index for rescanning the buffer.
195 (defconst imenu--rescan-item '("*Rescan*" . -99))
197 ;; The latest buffer index.
199 (defvar imenu--index-alist nil)
200 (make-variable-buffer-local 'imenu--index-alist)
202 ;; History list for 'jump-to-function-in-buffer'.
204 (defvar imenu--history-list nil)
205 (make-variable-buffer-local 'imenu--history-list)
207 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
209 ;;; Internal support functions
211 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
215 ;;; Sorts the items depending on their index name.
216 ;;; An item look like (NAME . POSITION).
218 (defun imenu--sort-by-name (item1 item2)
219 (string-lessp (car item1) (car item2)))
221 (defun imenu--relative-position (&optional reverse)
222 ;; Support function to calculate relative position in buffer
223 ;; Beginning of buffer is 0 and end of buffer is 100
224 ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
226 (total (buffer-size)))
227 (and reverse (setq pos (- total pos)))
229 ;; Avoid overflow from multiplying by 100!
230 (/ (1- pos) (max (/ total 100) 1))
231 (/ (* 100 (1- pos)) (max total 1)))))
234 ;;; Macro to display a progress message. This will probably be used
235 ;;; in a tight loop, that is why we use a macro.
236 ;;; RELPOS is the relative position to display.
237 ;;; If RELPOS is nil, then the relative position in the buffer
239 (defmacro imenu-progress-message (&optional relpos reverse)
241 imenu-scanning-message
242 (message imenu-scanning-message
245 (` (imenu--relative-position (, reverse)))))))))
248 ;;; Function for suporting general looking submenu names.
249 ;;; Uses `imenu-submenu-name-format' for creating the name.
250 ;;; NAME is the base of the new submenu name.
252 (defun imenu-create-submenu-name (name)
253 (format imenu-submenu-name-format name))
255 ;; Split LIST into sublists of max length N.
256 ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
257 (defun imenu--split (list n)
263 (push (pop remain) sublist)
266 ;; We have finished a sublist
267 (progn (push (nreverse sublist) result)
269 (setq sublist '()))))
270 ;; There might be a sublist (if the length of LIST mod n is != 0)
271 ;; that has to be added to the result list.
273 (push (nreverse sublist) result))
277 ;;; Split a menu in to several menus.
279 (defun imenu--split-menu (menulist title)
280 (cons "Function menus"
284 (cons (format "(%s)" title) menu)))
285 (imenu--split menulist imenu-max-items))))
288 ;;; Find all items in this buffer that should be in the index.
289 ;;; Returns an alist on the form
290 ;;; ((NAME . POSITION) (NAME . POSITION) ...)
293 (defun imenu--make-index-alist ()
294 ;; Create a list for this buffer only when needed.
295 (or imenu--index-alist
297 (setq imenu--index-alist
299 (funcall imenu-create-index-function))))
300 (or imenu--index-alist
301 (error "No items suitable for an index found in this buffer."))
302 ;; Add a rescan option to the index.
303 (cons imenu--rescan-item imenu--index-alist))
305 (defun imenu-default-create-index-function ()
306 "*Wrapper for index searching functions.
308 Moves point to end of buffer and then repeatedly calls
309 `prev-index-position-function' and `extract-index-name-function'.
310 Their results are gathered into an index alist."
312 (or (and (fboundp prev-index-position-function)
313 (fboundp extract-index-name-function))
314 (error "The mode \"%s\" does not take full advantage of imenu.el yet."
316 (let ((index-alist '())
318 (goto-char (point-max))
319 (imenu-progress-message 0 t)
320 ;; Search for the function
321 (while (funcall prev-index-position-function)
322 (imenu-progress-message nil t)
324 (setq name (funcall extract-index-name-function)))
326 (push (cons name (point)) index-alist)))
327 (imenu-progress-message 100 t)
330 (defun imenu--replace-spaces (name replacement)
331 ;; Replace all spaces in NAME with REPLACEMENT.
332 ;; That second argument should be a string.
336 (if (char-equal ch ?\ )
338 (char-to-string ch))))
342 (defun imenu--flatten-index-alist (index-alist &optional concat-names prefix)
343 ;; Takes a nested INDEX-ALIST and returns a flat index alist.
344 ;; If optional CONCAT-NAMES is non-nil, then a nested index has its
345 ;; name and a space concatenated to the names of the children.
346 ;; Third argument PREFIX is for internal use only.
350 (let* ((name (car item))
352 (new-prefix (and concat-names
354 (concat prefix imenu-level-separator name)
358 (list (cons new-prefix pos)))
360 (imenu--flatten-index-alist pos new-prefix))))))
363 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
365 ;;; The main functions for this package!
367 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
369 (defun imenu--completion-buffer (index-alist &optional prompt)
370 "Let the user select from INDEX-ALIST in a completion buffer with PROMPT.
372 Returns t for rescan and otherwise a position number."
373 ;; Create a list for this buffer only when needed.
375 (prepared-index-alist
379 (cons (imenu--replace-spaces (car item) imenu-space-replacement)
382 (save-window-excursion
383 ;; Display the completion buffer
384 (with-output-to-temp-buffer "*Completions*"
385 (display-completion-list
386 (all-completions "" prepared-index-alist )))
387 ;; Make a completion question
388 (setq name (completing-read (or prompt "Index item: ")
390 nil t nil 'imenu--history-list)))
392 ((not (stringp name))
394 ((string= name (car imenu--rescan-item))
397 (setq choice (assoc name prepared-index-alist))
399 ((listp (cdr choice))
400 (imenu--completion-buffer (cdr choice) prompt))
403 (defun imenu--mouse-menu (index-alist event &optional title)
404 "Let the user select from a buffer index from a mouse menu.
406 INDEX-ALIST is the buffer index and EVENT is a mouse event.
408 Returns t for rescan and otherwise a position number."
409 (let* ((menu (imenu--split-menu
410 (if imenu-sort-function
413 (oldlist index-alist))
414 ;; Copy list method from the cl package `copy-list'
415 (while (consp oldlist) (push (pop oldlist) res))
416 (prog1 (nreverse res) (setcdr res oldlist)))
419 (or title (buffer-name))))
421 (setq position (x-popup-menu event menu))
426 (imenu--mouse-menu position event
428 (concat title imenu-level-separator
429 (car (rassq position index-alist)))
430 (car (rassq position index-alist)))))
431 ((= position (cdr imenu--rescan-item))
434 (rassq position index-alist)))))
436 (defun imenu-choose-buffer-index (&optional prompt alist)
437 "Let the user select from a buffer index and return the chosen index.
439 If the user originally activated this function with the mouse, a mouse
440 menu is used. Otherwise a completion buffer is used and the user is
441 prompted with PROMPT.
443 If you call this function with index alist ALIST, then it lets the user
446 With no index alist ALIST, it calls `imenu--make-index-alist' to
447 create the index alist.
449 If `imenu-always-use-completion-buffer-p' is non-nil, then the
450 completion buffer is always used, no matter if the mouse was used or
453 The returned value is on the form (INDEX-NAME . INDEX-POSITION)."
455 (mouse-triggered (listp last-command-event))
457 ;; If selected by mouse, see to that the window where the mouse is
458 ;; really is selected.
460 (let ((window (posn-window (event-start last-command-event))))
461 (or (framep window) (select-window window))))
462 ;; Create a list for this buffer only when needed.
464 (setq index-alist (if alist alist (imenu--make-index-alist)))
466 (if (and mouse-triggered
467 (not imenu-always-use-completion-buffer-p))
468 (imenu--mouse-menu index-alist last-command-event)
469 (imenu--completion-buffer index-alist prompt)))
471 (setq imenu--index-alist nil)))
474 (defun goto-index-pos ()
475 "Jump to selected part of buffer, using a buffer menu or mouse menu.
477 See `imenu-choose-buffer-index' for more information."
479 (let ((index-item (imenu-choose-buffer-index)))
483 (goto-char (cdr index-item))))))
485 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
487 ;;;; Some examples of functions utilizing the framework of this
490 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
492 ;; Return the current/previous sexp and the location of the sexp (it's
493 ;; beginning) without moving the point.
494 (defun imenu-example--name-and-position ()
498 (end (progn (forward-sexp) (point))))
499 (cons (buffer-substring beg end)
506 (defun imenu-example--lisp-extract-index-name ()
507 ;; Example of a candidate for `imenu-extract-index-name-function'.
508 ;; This will generate a flat index of definitions in a lisp file.
510 (and (looking-at "(def")
516 (end (progn (forward-sexp -1) (point))))
517 (buffer-substring beg end)))
520 (defun imenu-example--create-lisp-index ()
521 ;; Example of a candidate for `imenu-create-index-function'.
522 ;; It will generate a nested index of definitions.
523 (let ((index-alist '())
524 (index-var-alist '())
525 (index-type-alist '())
526 (index-unknown-alist '()))
527 (goto-char (point-max))
528 (imenu-progress-message 0)
529 ;; Search for the function
530 (while (beginning-of-defun)
531 (imenu-progress-message nil t)
533 (and (looking-at "(def")
537 ((looking-at "def\\(var\\|const\\)")
539 (push (imenu-example--name-and-position)
541 ((looking-at "def\\(un\\|subst\\|macro\\|advice\\)")
543 (push (imenu-example--name-and-position)
545 ((looking-at "def\\(type\\|struct\\|class\\|ine-condition\\)")
547 (if (= (char-after (1- (point))) ?\))
552 (push (imenu-example--name-and-position)
556 (push (imenu-example--name-and-position)
557 index-unknown-alist)))))))
558 (imenu-progress-message 100)
560 (push (cons (imenu-create-submenu-name "Variables") index-var-alist)
562 (and index-type-alist
563 (push (cons (imenu-create-submenu-name "Types") index-type-alist)
565 (and index-unknown-alist
566 (push (cons (imenu-create-submenu-name "Syntax-unknown") index-unknown-alist)
574 ;; Regular expression to find C functions
575 (defvar imenu-example--function-name-regexp-c
577 "^[a-zA-Z0-9]+[ \t]?" ; type specs; there can be no
578 "\\([a-zA-Z0-9_*]+[ \t]+\\)?" ; more than 3 tokens, right?
579 "\\([a-zA-Z0-9_*]+[ \t]+\\)?"
580 "\\([*&]+[ \t]*\\)?" ; pointer
581 "\\([a-zA-Z0-9_*]+\\)[ \t]*(" ; name
584 (defun imenu-example--create-c-index (&optional regexp)
585 (let ((index-alist '())
587 (goto-char (point-min))
588 (imenu-progress-message 0)
589 ;; Search for the function
591 (while (re-search-forward
592 (or regexp imenu-example--function-name-regexp-c)
594 (imenu-progress-message)
597 (goto-char (scan-sexps (point) 1))
598 (setq char (following-char)))
599 ;; Skip this function name if it is a prototype declaration.
600 (if (not (eq char ?\;))
601 (push (imenu-example--name-and-position) index-alist))))
602 (imenu-progress-message 100)
603 (nreverse index-alist)))
608 ;; Regular expression to find C++ functions
609 (defvar imenu-example--function-name-regexp-c++
611 "^[a-zA-Z0-9:]+[ \t]?" ; type specs; there can be no
612 "\\([a-zA-Z0-9_:~*]+[ \t]+\\)?" ; more than 3 tokens, right?
613 "\\([a-zA-Z0-9_:~*]+[ \t]+\\)?"
614 "\\([*&]+[ \t]*\\)?" ; pointer
615 "\\([a-zA-Z0-9_:*]+\\)[ \t]*(" ; name
617 (defun imenu-example--create-c++-index ()
618 (imenu-example--create-c-index imenu-example--function-name-regexp-c++))
622 ;;; Example of hooks for the examples above
623 ;;; Put this in your .emacs.
625 ;; (add-hook 'emacs-lisp-mode-hook
628 ;; (setq imenu-create-index-function
629 ;; (function imenu-example--create-lisp-index)))))
631 ;; (add-hook 'lisp-mode-hook
634 ;; (setq imenu-create-index-function
635 ;; (function imenu-example--create-lisp-index)))))
637 ;; (add-hook 'c++-mode-hook
640 ;; (setq imenu-create-index-function
641 ;; (function imenu-example--create-c++-index)))))
643 ;; (add-hook 'c-mode-hook
646 ;; (setq imenu-create-index-function
647 ;; (function imenu-example--create-c-index)))))
651 ;;; imenu.el ends here