(do_check_ram_size): Don't hardcode the lisp address space size.
[emacs.git] / lisp / imenu.el
blob42f50fba3a4f080a7455347cce5ae7d837249d96
1 ;;; imenu.el --- framework for mode-specific buffer indexes
3 ;; Copyright (C) 1994, 1995, 1996, 1997, 1998, 2003 Free Software Foundation, Inc.
5 ;; Author: Ake Stenhoff <etxaksf@aom.ericsson.se>
6 ;; Lars Lindberg <lli@sypro.cap.se>
7 ;; Maintainer: FSF
8 ;; Created: 8 Feb 1994
9 ;; Keywords: tools convenience
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to the
25 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
26 ;; Boston, MA 02111-1307, USA.
28 ;;; Commentary:
30 ;; Purpose of this package:
31 ;; To present a framework for mode-specific buffer indexes.
32 ;; A buffer index is an alist of names and buffer positions.
33 ;; For instance all functions in a C-file and their positions.
35 ;; It is documented in the Emacs Lisp manual.
37 ;; How it works:
39 ;; A mode-specific function is called to generate the index. It is
40 ;; then presented to the user, who can choose from this index.
42 ;; The package comes with a set of example functions for how to
43 ;; utilize this package.
45 ;; There are *examples* for index gathering functions/regular
46 ;; expressions for C/C++ and Lisp/Emacs Lisp but it is easy to
47 ;; customize for other modes. A function for jumping to the chosen
48 ;; index position is also supplied.
50 ;;; History:
51 ;; Thanks go to
52 ;; [simon] - Simon Leinen simon@lia.di.epfl.ch
53 ;; [dean] - Dean Andrews ada@unison.com
54 ;; [alon] - Alon Albert al@mercury.co.il
55 ;; [greg] - Greg Thompson gregt@porsche.visix.COM
56 ;; [wolfgang] - Wolfgang Bangerth zcg51122@rpool1.rus.uni-stuttgart.de
57 ;; [kai] - Kai Grossjohann grossjoh@linus.informatik.uni-dortmund.de
58 ;; [david] - David M. Smith dsmith@stats.adelaide.edu.au
59 ;; [christian] - Christian Egli Christian.Egli@hcsd.hac.com
60 ;; [karl] - Karl Fogel kfogel@floss.life.uiuc.edu
62 ;;; Code:
64 (eval-when-compile (require 'cl))
66 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
67 ;;;
68 ;;; Customizable variables
69 ;;;
70 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
72 (defgroup imenu nil
73 "Mode-specific buffer indexes."
74 :group 'matching
75 :group 'frames
76 :group 'convenience
77 :link '(custom-manual "(elisp)Imenu"))
79 (defcustom imenu-use-markers t
80 "*Non-nil means use markers instead of integers for Imenu buffer positions.
82 Setting this to nil makes Imenu work a little faster but editing the
83 buffer will make the generated index positions wrong.
85 This might not yet be honored by all index-building functions."
86 :type 'boolean
87 :group 'imenu)
90 (defcustom imenu-max-item-length 60
91 "*If a number, truncate Imenu entries to that length."
92 :type '(choice integer
93 (const :tag "Unlimited"))
94 :group 'imenu)
96 (defcustom imenu-auto-rescan nil
97 "*Non-nil means Imenu should always rescan the buffers."
98 :type 'boolean
99 :group 'imenu)
101 (defcustom imenu-auto-rescan-maxout 60000
102 "*Imenu auto-rescan is disabled in buffers larger than this size (in bytes).
103 This variable is buffer-local."
104 :type 'integer
105 :group 'imenu)
107 (defvar imenu-always-use-completion-buffer-p nil)
108 (make-obsolete-variable 'imenu-always-use-completion-buffer-p
109 'imenu-use-popup-menu "21.4")
111 (defcustom imenu-use-popup-menu
112 (if imenu-always-use-completion-buffer-p
113 (not (eq imenu-always-use-completion-buffer-p 'never))
114 'on-mouse)
115 "Use a popup menu rather than a minibuffer prompt.
116 If nil, always use a minibuffer prompt.
117 If t, always use a popup menu,
118 If `on-mouse' use a popup menu when `imenu' was invoked with the mouse."
119 :type '(choice (const :tag "On Mouse" on-mouse)
120 (const :tag "Never" nil)
121 (other :tag "Always" t)))
123 (defcustom imenu-eager-completion-buffer
124 (not (eq imenu-always-use-completion-buffer-p 'never))
125 "If non-nil, eagerly popup the completion buffer."
126 :type 'boolean)
128 (defcustom imenu-after-jump-hook nil
129 "*Hooks called after jumping to a place in the buffer.
131 Useful things to use here include `reposition-window', `recenter', and
132 \(lambda () (recenter 0)) to show at top of screen."
133 :type 'hook
134 :group 'imenu)
136 ;;;###autoload
137 (defcustom imenu-sort-function nil
138 "*The function to use for sorting the index mouse-menu.
140 Affects only the mouse index menu.
142 Set this to nil if you don't want any sorting (faster).
143 The items in the menu are then presented in the order they were found
144 in the buffer.
146 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
148 The function should take two arguments and return t if the first
149 element should come before the second. The arguments are cons cells;
150 \(NAME . POSITION). Look at `imenu--sort-by-name' for an example."
151 :type '(choice (const :tag "No sorting" nil)
152 (const :tag "Sort by name" imenu--sort-by-name)
153 (function :tag "Another function"))
154 :group 'imenu)
156 (defcustom imenu-max-items 25
157 "*Maximum number of elements in a mouse menu for Imenu."
158 :type 'integer
159 :group 'imenu)
161 (defcustom imenu-scanning-message "Scanning buffer for index (%3d%%)"
162 "*Progress message during the index scanning of the buffer.
163 If non-nil, user gets a message during the scanning of the buffer.
165 Relevant only if the mode-specific function that creates the buffer
166 index use `imenu-progress-message', and not useful if that is fast, in
167 which case you might as well set this to nil."
168 :type '(choice string
169 (const :tag "None" nil))
170 :group 'imenu)
172 (defcustom imenu-space-replacement "."
173 "*The replacement string for spaces in index names.
174 Used when presenting the index in a completion buffer to make the
175 names work as tokens."
176 :type '(choice string (const nil))
177 :group 'imenu)
179 (defcustom imenu-level-separator ":"
180 "*The separator between index names of different levels.
181 Used for making mouse-menu titles and for flattening nested indexes
182 with name concatenation."
183 :type 'string
184 :group 'imenu)
186 ;;;###autoload
187 (defvar imenu-generic-expression nil
188 "The regex pattern to use for creating a buffer index.
190 If non-nil this pattern is passed to `imenu--generic-function'
191 to create a buffer index.
193 The value should be an alist with elements that look like this:
194 (MENU-TITLE REGEXP INDEX)
195 or like this:
196 (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)
197 with zero or more ARGUMENTS. The former format creates a simple element in
198 the index alist when it matches; the latter creates a special element
199 of the form (NAME POSITION-MARKER FUNCTION ARGUMENTS...)
200 with FUNCTION and ARGUMENTS copied from `imenu-generic-expression'.
202 MENU-TITLE is a string used as the title for the submenu or nil if the
203 entries are not nested.
205 REGEXP is a regexp that should match a construct in the buffer that is
206 to be displayed in the menu; i.e., function or variable definitions,
207 etc. It contains a substring which is the name to appear in the
208 menu. See the info section on Regexps for more information.
210 INDEX points to the substring in REGEXP that contains the name (of the
211 function, variable or type) that is to appear in the menu.
213 The variable is buffer-local.
215 The variable `imenu-case-fold-search' determines whether or not the
216 regexp matches are case sensitive, and `imenu-syntax-alist' can be
217 used to alter the syntax table for the search.
219 For example, see the value of `fortran-imenu-generic-expression' used by
220 `fortran-mode' with `imenu-syntax-alist' set locally to give the
221 characters which normally have \"symbol\" syntax \"word\" syntax
222 during matching.")
224 ;;;###autoload
225 (make-variable-buffer-local 'imenu-generic-expression)
227 ;;;; Hooks
229 ;;;###autoload
230 (defvar imenu-create-index-function 'imenu-default-create-index-function
231 "The function to use for creating a buffer index.
233 It should be a function that takes no arguments and returns an index
234 of the current buffer as an alist.
236 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
237 Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
238 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
239 The function `imenu--subalist-p' tests an element and returns t
240 if it is a sub-alist.
242 This function is called within a `save-excursion'.
244 The variable is buffer-local.")
245 ;;;###autoload
246 (make-variable-buffer-local 'imenu-create-index-function)
248 ;;;###autoload
249 (defvar imenu-prev-index-position-function 'beginning-of-defun
250 "Function for finding the next index position.
252 If `imenu-create-index-function' is set to
253 `imenu-default-create-index-function', then you must set this variable
254 to a function that will find the next index, looking backwards in the
255 file.
257 The function should leave point at the place to be connected to the
258 index and it should return nil when it doesn't find another index.
260 This variable is local in all buffers.")
261 ;;;###autoload
262 (make-variable-buffer-local 'imenu-prev-index-position-function)
264 ;;;###autoload
265 (defvar imenu-extract-index-name-function nil
266 "Function for extracting the index item name, given a position.
268 This function is called after `imenu-prev-index-position-function'
269 finds a position for an index item, with point at that position.
270 It should return the name for that index item.
272 This variable is local in all buffers.")
273 ;;;###autoload
274 (make-variable-buffer-local 'imenu-extract-index-name-function)
276 ;;;###autoload
277 (defvar imenu-name-lookup-function nil
278 "Function to compare string with index item.
280 This function will be called with two strings, and should return
281 non-nil if they match.
283 If nil, comparison is done with `string='.
284 Set this to some other function for more advanced comparisons,
285 such as \"begins with\" or \"name matches and number of
286 arguments match\".
288 This variable is local in all buffers.")
289 ;;;###autoload
290 (make-variable-buffer-local 'imenu-name-lookup-function)
292 ;;;###autoload
293 (defvar imenu-default-goto-function 'imenu-default-goto-function
294 "The default function called when selecting an Imenu item.
295 The function in this variable is called when selecting a normal index-item.")
296 ;;;###autoload
297 (make-variable-buffer-local 'imenu-default-goto-function)
300 (defun imenu--subalist-p (item)
301 (and (consp (cdr item)) (listp (cadr item))
302 (not (eq (car (cadr item)) 'lambda))))
304 ;; Macro to display a progress message.
305 ;; RELPOS is the relative position to display.
306 ;; If RELPOS is nil, then the relative position in the buffer
307 ;; is calculated.
308 ;; PREVPOS is the variable in which we store the last position displayed.
309 (defmacro imenu-progress-message (prevpos &optional relpos reverse)
310 `(and
311 imenu-scanning-message
312 (let ((pos ,(if relpos
313 relpos
314 `(imenu--relative-position ,reverse))))
315 (if ,(if relpos t
316 `(> pos (+ 5 ,prevpos)))
317 (progn
318 (message imenu-scanning-message pos)
319 (setq ,prevpos pos))))))
322 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
323 ;;;;
324 ;;;; Some examples of functions utilizing the framework of this
325 ;;;; package.
326 ;;;;
327 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
329 ;; Return the current/previous sexp and the location of the sexp (its
330 ;; beginning) without moving the point.
331 (defun imenu-example--name-and-position ()
332 (save-excursion
333 (forward-sexp -1)
334 ;; [ydi] modified for imenu-use-markers
335 (let ((beg (if imenu-use-markers (point-marker) (point)))
336 (end (progn (forward-sexp) (point))))
337 (cons (buffer-substring beg end)
338 beg))))
341 ;;; Lisp
344 (defun imenu-example--lisp-extract-index-name ()
345 ;; Example of a candidate for `imenu-extract-index-name-function'.
346 ;; This will generate a flat index of definitions in a lisp file.
347 (save-match-data
348 (and (looking-at "(def")
349 (condition-case nil
350 (progn
351 (down-list 1)
352 (forward-sexp 2)
353 (let ((beg (point))
354 (end (progn (forward-sexp -1) (point))))
355 (buffer-substring beg end)))
356 (error nil)))))
358 (defun imenu-example--create-lisp-index ()
359 ;; Example of a candidate for `imenu-create-index-function'.
360 ;; It will generate a nested index of definitions.
361 (let ((index-alist '())
362 (index-var-alist '())
363 (index-type-alist '())
364 (index-unknown-alist '())
365 prev-pos)
366 (goto-char (point-max))
367 (imenu-progress-message prev-pos 0)
368 ;; Search for the function
369 (while (beginning-of-defun)
370 (imenu-progress-message prev-pos nil t)
371 (save-match-data
372 (and (looking-at "(def")
373 (save-excursion
374 (down-list 1)
375 (cond
376 ((looking-at "def\\(var\\|const\\)")
377 (forward-sexp 2)
378 (push (imenu-example--name-and-position)
379 index-var-alist))
380 ((looking-at "def\\(un\\|subst\\|macro\\|advice\\)")
381 (forward-sexp 2)
382 (push (imenu-example--name-and-position)
383 index-alist))
384 ((looking-at "def\\(type\\|struct\\|class\\|ine-condition\\)")
385 (forward-sexp 2)
386 (if (= (char-after (1- (point))) ?\))
387 (progn
388 (forward-sexp -1)
389 (down-list 1)
390 (forward-sexp 1)))
391 (push (imenu-example--name-and-position)
392 index-type-alist))
394 (forward-sexp 2)
395 (push (imenu-example--name-and-position)
396 index-unknown-alist)))))))
397 (imenu-progress-message prev-pos 100)
398 (and index-var-alist
399 (push (cons "Variables" index-var-alist)
400 index-alist))
401 (and index-type-alist
402 (push (cons "Types" index-type-alist)
403 index-alist))
404 (and index-unknown-alist
405 (push (cons "Syntax-unknown" index-unknown-alist)
406 index-alist))
407 index-alist))
409 ;; Regular expression to find C functions
410 (defvar imenu-example--function-name-regexp-c
411 (concat
412 "^[a-zA-Z0-9]+[ \t]?" ; type specs; there can be no
413 "\\([a-zA-Z0-9_*]+[ \t]+\\)?" ; more than 3 tokens, right?
414 "\\([a-zA-Z0-9_*]+[ \t]+\\)?"
415 "\\([*&]+[ \t]*\\)?" ; pointer
416 "\\([a-zA-Z0-9_*]+\\)[ \t]*(" ; name
419 (defun imenu-example--create-c-index (&optional regexp)
420 (let ((index-alist '())
421 prev-pos char)
422 (goto-char (point-min))
423 (imenu-progress-message prev-pos 0)
424 ;; Search for the function
425 (save-match-data
426 (while (re-search-forward
427 (or regexp imenu-example--function-name-regexp-c)
428 nil t)
429 (imenu-progress-message prev-pos)
430 (backward-up-list 1)
431 (save-excursion
432 (goto-char (scan-sexps (point) 1))
433 (setq char (following-char)))
434 ;; Skip this function name if it is a prototype declaration.
435 (if (not (eq char ?\;))
436 (push (imenu-example--name-and-position) index-alist))))
437 (imenu-progress-message prev-pos 100)
438 (nreverse index-alist)))
441 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
443 ;;; Internal variables
445 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
447 ;; The item to use in the index for rescanning the buffer.
448 (defconst imenu--rescan-item '("*Rescan*" . -99))
450 ;; The latest buffer index.
451 ;; Buffer local.
452 (defvar imenu--index-alist nil
453 "The buffer index computed for this buffer in Imenu.
454 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
455 Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
456 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
458 This variable is local in all buffers, once set.")
460 (make-variable-buffer-local 'imenu--index-alist)
462 (defvar imenu--last-menubar-index-alist nil
463 "The latest buffer index used to update the menu bar menu.")
465 (make-variable-buffer-local 'imenu--last-menubar-index-alist)
467 ;; History list for 'jump-to-function-in-buffer'.
468 ;; Making this buffer local caused it not to work!
469 (defvar imenu--history-list nil)
471 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
473 ;;; Internal support functions
475 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
478 ;;; Sort function
479 ;;; Sorts the items depending on their index name.
480 ;;; An item looks like (NAME . POSITION).
482 (defun imenu--sort-by-name (item1 item2)
483 (string-lessp (car item1) (car item2)))
485 (defun imenu--sort-by-position (item1 item2)
486 (< (cdr item1) (cdr item2)))
488 (defun imenu--relative-position (&optional reverse)
489 ;; Support function to calculate relative position in buffer
490 ;; Beginning of buffer is 0 and end of buffer is 100
491 ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
492 (let ((pos (point))
493 (total (buffer-size)))
494 (and reverse (setq pos (- total pos)))
495 (if (> total 50000)
496 ;; Avoid overflow from multiplying by 100!
497 (/ (1- pos) (max (/ total 100) 1))
498 (/ (* 100 (1- pos)) (max total 1)))))
500 ;; Split LIST into sublists of max length N.
501 ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
502 (defun imenu--split (list n)
503 (let ((remain list)
504 (result '())
505 (sublist '())
506 (i 0))
507 (while remain
508 (push (pop remain) sublist)
509 (incf i)
510 (and (= i n)
511 ;; We have finished a sublist
512 (progn (push (nreverse sublist) result)
513 (setq i 0)
514 (setq sublist '()))))
515 ;; There might be a sublist (if the length of LIST mod n is != 0)
516 ;; that has to be added to the result list.
517 (and sublist
518 (push (nreverse sublist) result))
519 (nreverse result)))
521 ;;; Split the alist MENULIST into a nested alist, if it is long enough.
522 ;;; In any case, add TITLE to the front of the alist.
523 (defun imenu--split-menu (menulist title)
524 (let (keep-at-top tail)
525 (if (memq imenu--rescan-item menulist)
526 (setq keep-at-top (cons imenu--rescan-item nil)
527 menulist (delq imenu--rescan-item menulist)))
528 (setq tail menulist)
529 (dolist (item tail)
530 (when (imenu--subalist-p item)
531 (push item keep-at-top)
532 (setq menulist (delq item menulist))))
533 (if imenu-sort-function
534 (setq menulist (sort menulist imenu-sort-function)))
535 (if (> (length menulist) imenu-max-items)
536 (setq menulist
537 (mapcar
538 (lambda (menu)
539 (cons (format "From: %s" (caar menu)) menu))
540 (imenu--split menulist imenu-max-items))))
541 (cons title
542 (nconc (nreverse keep-at-top) menulist))))
544 ;;; Split up each long alist that are nested within ALIST
545 ;;; into nested alists.
546 (defun imenu--split-submenus (alist)
547 (mapcar (function
548 (lambda (elt)
549 (if (and (consp elt)
550 (stringp (car elt))
551 (listp (cdr elt)))
552 (imenu--split-menu (cdr elt) (car elt))
553 elt)))
554 alist))
556 ;;; Truncate all strings in MENULIST to imenu-max-item-length
557 (defun imenu--truncate-items (menulist)
558 (mapcar (function
559 (lambda (item)
560 (cond
561 ((consp (cdr item))
562 (imenu--truncate-items (cdr item)))
564 ;; truncate if necessary
565 (if (and (numberp imenu-max-item-length)
566 (> (length (car item)) imenu-max-item-length))
567 (setcar item (substring (car item) 0
568 imenu-max-item-length)))))))
569 menulist))
572 (defun imenu--make-index-alist (&optional noerror)
573 "Create an index-alist for the definitions in the current buffer.
575 Report an error if the list is empty unless NOERROR is supplied and
576 non-nil.
578 Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
579 Special elements look like (INDEX-NAME FUNCTION ARGUMENTS...).
580 A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
581 The function `imenu--subalist-p' tests an element and returns t
582 if it is a sub-alist.
584 There is one simple element with negative POSITION; that's intended
585 as a way for the user to ask to recalculate the buffer's index alist."
586 (or (and imenu--index-alist
587 (or (not imenu-auto-rescan)
588 (and imenu-auto-rescan
589 (> (buffer-size) imenu-auto-rescan-maxout))))
590 ;; Get the index; truncate if necessary
591 (progn
592 (setq imenu--index-alist
593 (save-excursion
594 (save-restriction
595 (widen)
596 (funcall imenu-create-index-function))))
597 (imenu--truncate-items imenu--index-alist)))
598 (or imenu--index-alist noerror
599 (error "No items suitable for an index found in this buffer"))
600 (or imenu--index-alist
601 (setq imenu--index-alist (list nil)))
602 ;; Add a rescan option to the index.
603 (cons imenu--rescan-item imenu--index-alist))
605 ;;; Find all markers in alist and makes
606 ;;; them point nowhere.
607 ;;; The top-level call uses nil as the argument;
608 ;;; non-nil arguments are in recursivecalls.
609 (defvar imenu--cleanup-seen)
611 (defun imenu--cleanup (&optional alist)
612 ;; If alist is provided use that list.
613 ;; If not, empty the table of lists already seen
614 ;; and use imenu--index-alist.
615 (if alist
616 (setq imenu--cleanup-seen (cons alist imenu--cleanup-seen))
617 (setq alist imenu--index-alist imenu--cleanup-seen (list alist)))
619 (and alist
620 (mapc
621 (lambda (item)
622 (cond
623 ((markerp (cdr item))
624 (set-marker (cdr item) nil))
625 ;; Don't process one alist twice.
626 ((memq (cdr item) imenu--cleanup-seen))
627 ((imenu--subalist-p item)
628 (imenu--cleanup (cdr item)))))
629 alist)
632 (defun imenu--create-keymap (title alist &optional cmd)
633 (list* 'keymap title
634 (mapcar
635 (lambda (item)
636 (list* (car item) (car item)
637 (cond
638 ((imenu--subalist-p item)
639 (imenu--create-keymap (car item) (cdr item) cmd))
641 `(lambda () (interactive)
642 ,(if cmd `(,cmd ',item) (list 'quote item)))))))
643 alist)))
645 (defun imenu--in-alist (str alist)
646 "Check whether the string STR is contained in multi-level ALIST."
647 (let (elt head tail res)
648 (setq res nil)
649 (while alist
650 (setq elt (car alist)
651 tail (cdr elt)
652 alist (cdr alist)
653 head (car elt))
654 ;; A nested ALIST element looks like
655 ;; (INDEX-NAME (INDEX-NAME . INDEX-POSITION) ...)
656 ;; while a bottom-level element looks like
657 ;; (INDEX-NAME . INDEX-POSITION)
658 ;; We are only interested in the bottom-level elements, so we need to
659 ;; recurse if TAIL is a list.
660 (cond ((listp tail)
661 (if (setq res (imenu--in-alist str tail))
662 (setq alist nil)))
663 ((if imenu-name-lookup-function
664 (funcall imenu-name-lookup-function str head)
665 (string= str head))
666 (setq alist nil res elt))))
667 res))
669 (defvar imenu-syntax-alist nil
670 "Alist of syntax table modifiers to use while in `imenu--generic-function'.
672 The car of the assocs may be either a character or a string and the
673 cdr is a syntax description appropriate for `modify-syntax-entry'. For
674 a string, all the characters in the string get the specified syntax.
676 This is typically used to give word syntax to characters which
677 normally have symbol syntax to simplify `imenu-expression'
678 and speed-up matching.")
679 ;;;###autoload
680 (make-variable-buffer-local 'imenu-syntax-alist)
682 (defun imenu-default-create-index-function ()
683 "*Wrapper for index searching functions.
685 Moves point to end of buffer and then repeatedly calls
686 `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
687 Their results are gathered into an index alist."
688 ;; These should really be done by setting imenu-create-index-function
689 ;; in these major modes. But save that change for later.
690 (cond ((and imenu-prev-index-position-function
691 imenu-extract-index-name-function)
692 (let ((index-alist '())
693 prev-pos name)
694 (goto-char (point-max))
695 (imenu-progress-message prev-pos 0 t)
696 ;; Search for the function
697 (while (funcall imenu-prev-index-position-function)
698 (imenu-progress-message prev-pos nil t)
699 (save-excursion
700 (setq name (funcall imenu-extract-index-name-function)))
701 (and (stringp name)
702 ;; [ydi] updated for imenu-use-markers
703 (push (cons name (if imenu-use-markers (point-marker) (point)))
704 index-alist)))
705 (imenu-progress-message prev-pos 100 t)
706 index-alist))
707 ;; Use generic expression if possible.
708 ((and imenu-generic-expression)
709 (imenu--generic-function imenu-generic-expression))
711 (error "This buffer cannot use `imenu-default-create-index-function'"))))
713 ;; Not used and would require cl at run time
714 ;; (defun imenu--flatten-index-alist (index-alist &optional concat-names prefix)
715 ;; ;; Takes a nested INDEX-ALIST and returns a flat index alist.
716 ;; ;; If optional CONCAT-NAMES is non-nil, then a nested index has its
717 ;; ;; name and a space concatenated to the names of the children.
718 ;; ;; Third argument PREFIX is for internal use only.
719 ;; (mapcan
720 ;; (lambda (item)
721 ;; (let* ((name (car item))
722 ;; (pos (cdr item))
723 ;; (new-prefix (and concat-names
724 ;; (if prefix
725 ;; (concat prefix imenu-level-separator name)
726 ;; name))))
727 ;; (cond
728 ;; ((or (markerp pos) (numberp pos))
729 ;; (list (cons new-prefix pos)))
730 ;; (t
731 ;; (imenu--flatten-index-alist pos new-prefix)))))
732 ;; index-alist))
735 ;;; Generic index gathering function.
738 (defvar imenu-case-fold-search t
739 "Defines whether `imenu--generic-function' should fold case when matching.
741 This variable should be set (only) by initialization code
742 for modes which use `imenu--generic-function'. If it is not set, but
743 `font-lock-defaults' is set, then font-lock's setting is used.")
744 ;;;###autoload
745 (make-variable-buffer-local 'imenu-case-fold-search)
747 ;; Originally "Built on some ideas that Erik Naggum <erik@naggum.no>
748 ;; once posted to comp.emacs" but since substantially re-written.
749 (defun imenu--generic-function (patterns)
750 "Return an index of the current buffer as an alist.
752 PATTERNS is an alist with elements that look like this:
753 (MENU-TITLE REGEXP INDEX).
754 or like this:
755 (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)
756 with zero or more ARGUMENTS.
758 MENU-TITLE is a string used as the title for the submenu or nil if the
759 entries are not nested.
761 REGEXP is a regexp that should match a construct in the buffer that is
762 to be displayed in the menu; i.e., function or variable definitions,
763 etc. It contains a substring which is the name to appear in the
764 menu. See the info section on Regexps for more information.
766 INDEX points to the substring in REGEXP that contains the name (of the
767 function, variable or type) that is to appear in the menu.
769 See `lisp-imenu-generic-expression' for an example of PATTERNS.
771 Returns an index of the current buffer as an alist. The elements in
772 the alist look like:
773 (INDEX-NAME . INDEX-POSITION)
774 or like:
775 (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)
776 They may also be nested index alists like:
777 (INDEX-NAME . INDEX-ALIST)
778 depending on PATTERNS."
780 (let ((index-alist (list 'dummy))
781 prev-pos beg
782 (case-fold-search (if (or (local-variable-p 'imenu-case-fold-search)
783 (not (local-variable-p 'font-lock-defaults)))
784 imenu-case-fold-search
785 (nth 2 font-lock-defaults)))
786 (old-table (syntax-table))
787 (table (copy-syntax-table (syntax-table)))
788 (slist imenu-syntax-alist))
789 ;; Modify the syntax table used while matching regexps.
790 (dolist (syn slist)
791 ;; The character(s) to modify may be a single char or a string.
792 (if (numberp (car syn))
793 (modify-syntax-entry (car syn) (cdr syn) table)
794 (mapc (lambda (c)
795 (modify-syntax-entry c (cdr syn) table))
796 (car syn))))
797 (goto-char (point-max))
798 (imenu-progress-message prev-pos 0 t)
799 (unwind-protect ; for syntax table
800 (save-match-data
801 (set-syntax-table table)
802 ;; map over the elements of imenu-generic-expression
803 ;; (typically functions, variables ...)
804 (dolist (pat patterns)
805 (let ((menu-title (car pat))
806 (regexp (nth 1 pat))
807 (index (nth 2 pat))
808 (function (nth 3 pat))
809 (rest (nthcdr 4 pat)))
810 ;; Go backwards for convenience of adding items in order.
811 (goto-char (point-max))
812 (while (re-search-backward regexp nil t)
813 (imenu-progress-message prev-pos nil t)
814 (setq beg (match-beginning index))
815 ;; Add this sort of submenu only when we've found an
816 ;; item for it, avoiding empty, duff menus.
817 (unless (assoc menu-title index-alist)
818 (push (list menu-title) index-alist))
819 (if imenu-use-markers
820 (setq beg (copy-marker beg)))
821 (let ((item
822 (if function
823 (nconc (list (match-string-no-properties index)
824 beg function)
825 rest)
826 (cons (match-string-no-properties index)
827 beg)))
828 ;; This is the desired submenu,
829 ;; starting with its title (or nil).
830 (menu (assoc menu-title index-alist)))
831 ;; Insert the item unless it is already present.
832 (unless (member item (cdr menu))
833 (setcdr menu
834 (cons item (cdr menu))))))))
835 (set-syntax-table old-table)))
836 (imenu-progress-message prev-pos 100 t)
837 ;; Sort each submenu by position.
838 ;; This is in case one submenu gets items from two different regexps.
839 (dolist (item index-alist)
840 (when (listp item)
841 (setcdr item (sort (cdr item) 'imenu--sort-by-position))))
842 (let ((main-element (assq nil index-alist)))
843 (nconc (delq main-element (delq 'dummy index-alist))
844 (cdr main-element)))))
846 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
848 ;;; The main functions for this package!
850 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
852 ;; See also info-lookup-find-item
853 (defun imenu-find-default (guess completions)
854 "Fuzzily find an item based on GUESS inside the alist COMPLETIONS."
855 (catch 'found
856 (let ((case-fold-search t))
857 (if (assoc guess completions) guess
858 (dolist (re (list (concat "\\`" (regexp-quote guess) "\\'")
859 (concat "\\`" (regexp-quote guess))
860 (concat (regexp-quote guess) "\\'")
861 (regexp-quote guess)))
862 (dolist (x completions)
863 (if (string-match re (car x)) (throw 'found (car x)))))))))
865 (defun imenu--completion-buffer (index-alist &optional prompt)
866 "Let the user select from INDEX-ALIST in a completion buffer with PROMPT.
868 Returns t for rescan and otherwise a position number."
869 ;; Create a list for this buffer only when needed.
870 (let ((name (thing-at-point 'symbol))
871 choice
872 (prepared-index-alist
873 (if (not imenu-space-replacement) index-alist
874 (mapcar
875 (lambda (item)
876 (cons (subst-char-in-string ?\ (aref imenu-space-replacement 0)
877 (car item))
878 (cdr item)))
879 index-alist))))
880 (when (stringp name)
881 (setq name (or (imenu-find-default name prepared-index-alist) name)))
882 (cond (prompt)
883 ((and name (imenu--in-alist name prepared-index-alist))
884 (setq prompt (format "Index item (default %s): " name)))
885 (t (setq prompt "Index item: ")))
886 (let ((minibuffer-setup-hook minibuffer-setup-hook))
887 ;; Display the completion buffer.
888 (if (not imenu-eager-completion-buffer)
889 (add-hook 'minibuffer-setup-hook 'minibuffer-completion-help))
890 (setq name (completing-read prompt
891 prepared-index-alist
892 nil t nil 'imenu--history-list name)))
893 (cond ((not (stringp name)) nil)
894 ((string= name (car imenu--rescan-item)) t)
896 (setq choice (assoc name prepared-index-alist))
897 (if (imenu--subalist-p choice)
898 (imenu--completion-buffer (cdr choice) prompt)
899 choice)))))
901 (defun imenu--mouse-menu (index-alist event &optional title)
902 "Let the user select from a buffer index from a mouse menu.
904 INDEX-ALIST is the buffer index and EVENT is a mouse event.
906 Returns t for rescan and otherwise an element or subelement of INDEX-ALIST."
907 (setq index-alist (imenu--split-submenus index-alist))
908 (let* ((menu (imenu--split-menu index-alist (or title (buffer-name))))
909 (map (imenu--create-keymap (car menu)
910 (cdr (if (< 1 (length (cdr menu)))
911 menu
912 (car (cdr menu)))))))
913 (popup-menu map event)))
915 (defun imenu-choose-buffer-index (&optional prompt alist)
916 "Let the user select from a buffer index and return the chosen index.
918 If the user originally activated this function with the mouse, a mouse
919 menu is used. Otherwise a completion buffer is used and the user is
920 prompted with PROMPT.
922 If you call this function with index alist ALIST, then it lets the user
923 select from ALIST.
925 With no index alist ALIST, it calls `imenu--make-index-alist' to
926 create the index alist.
928 If `imenu-use-popup-menu' is non-nil, then the
929 completion buffer is always used, no matter if the mouse was used or
930 not.
932 The returned value is of the form (INDEX-NAME . INDEX-POSITION)."
933 (let (index-alist
934 (mouse-triggered (listp last-nonmenu-event))
935 (result t))
936 ;; If selected by mouse, see to that the window where the mouse is
937 ;; really is selected.
938 (and mouse-triggered
939 (not (equal last-nonmenu-event '(menu-bar)))
940 (let ((window (posn-window (event-start last-nonmenu-event))))
941 (or (framep window) (null window) (select-window window))))
942 ;; Create a list for this buffer only when needed.
943 (while (eq result t)
944 (setq index-alist (if alist alist (imenu--make-index-alist)))
945 (setq result
946 (if (and imenu-use-popup-menu
947 (or (eq imenu-use-popup-menu t) mouse-triggered))
948 (imenu--mouse-menu index-alist last-nonmenu-event)
949 (imenu--completion-buffer index-alist prompt)))
950 (and (eq result t)
951 (imenu--cleanup)
952 (setq imenu--index-alist nil)))
953 result))
955 ;;;###autoload
956 (defun imenu-add-to-menubar (name)
957 "Add an `imenu' entry to the menu bar for the current buffer.
958 NAME is a string used to name the menu bar item.
959 See the command `imenu' for more information."
960 (interactive "sImenu menu item name: ")
961 (if (or (and imenu-prev-index-position-function
962 imenu-extract-index-name-function)
963 imenu-generic-expression
964 (not (eq imenu-create-index-function
965 'imenu-default-create-index-function)))
966 (let ((newmap (make-sparse-keymap)))
967 (set-keymap-parent newmap (current-local-map))
968 (setq imenu--last-menubar-index-alist nil)
969 (define-key newmap [menu-bar index]
970 `(menu-item ,name ,(make-sparse-keymap "Imenu")))
971 (use-local-map newmap)
972 (add-hook 'menu-bar-update-hook 'imenu-update-menubar))
973 (error "The mode `%s' does not support Imenu" mode-name)))
975 ;;;###autoload
976 (defun imenu-add-menubar-index ()
977 "Add an Imenu \"Index\" entry on the menu bar for the current buffer.
979 A trivial interface to `imenu-add-to-menubar' suitable for use in a hook."
980 (interactive)
981 (imenu-add-to-menubar "Index"))
983 (defvar imenu-buffer-menubar nil)
985 (defvar imenu-menubar-modified-tick 0
986 "The value of (buffer-modified-tick) as of last call to `imenu-update-menubar'.
987 This value becomes local in every buffer when it is set.")
988 (make-variable-buffer-local 'imenu-menubar-modified-tick)
990 (defun imenu-update-menubar ()
991 (when (and (current-local-map)
992 (keymapp (lookup-key (current-local-map) [menu-bar index]))
993 (not (eq (buffer-modified-tick)
994 imenu-menubar-modified-tick)))
995 (setq imenu-menubar-modified-tick (buffer-modified-tick))
996 (let ((index-alist (imenu--make-index-alist t)))
997 ;; Don't bother updating if the index-alist has not changed
998 ;; since the last time we did it.
999 (unless (equal index-alist imenu--last-menubar-index-alist)
1000 (let (menu menu1 old)
1001 (setq imenu--last-menubar-index-alist index-alist)
1002 (setq index-alist (imenu--split-submenus index-alist))
1003 (setq menu (imenu--split-menu index-alist
1004 (buffer-name)))
1005 (setq menu1 (imenu--create-keymap (car menu)
1006 (cdr (if (< 1 (length (cdr menu)))
1007 menu
1008 (car (cdr menu))))
1009 'imenu--menubar-select))
1010 (setq old (lookup-key (current-local-map) [menu-bar index]))
1011 (setcdr old (cdr menu1)))))))
1013 (defun imenu--menubar-select (item)
1014 "Use Imenu to select the function or variable named in this menu ITEM."
1015 (if (equal item imenu--rescan-item)
1016 (progn
1017 (imenu--cleanup)
1018 (setq imenu--index-alist nil)
1019 (imenu-update-menubar)
1021 (imenu item)
1022 nil))
1024 (defun imenu-default-goto-function (name position &optional rest)
1025 "Move the point to the given position.
1027 NAME is ignored. POSITION is where to move. REST is also ignored.
1028 The ignored args just make this function have the same interface as a
1029 function placed in a special index-item."
1030 (if (or (< position (point-min))
1031 (> position (point-max)))
1032 ;; widen if outside narrowing
1033 (widen))
1034 (goto-char position))
1036 ;;;###autoload
1037 (defun imenu (index-item)
1038 "Jump to a place in the buffer chosen using a buffer menu or mouse menu.
1039 INDEX-ITEM specifies the position. See `imenu-choose-buffer-index'
1040 for more information."
1041 (interactive (list (imenu-choose-buffer-index)))
1042 ;; Convert a string to an alist element.
1043 (if (stringp index-item)
1044 (setq index-item (assoc index-item (imenu--make-index-alist))))
1045 (when index-item
1046 (push-mark)
1047 (let* ((is-special-item (listp (cdr index-item)))
1048 (function
1049 (if is-special-item
1050 (nth 2 index-item) imenu-default-goto-function))
1051 (position (if is-special-item
1052 (cadr index-item) (cdr index-item)))
1053 (rest (if is-special-item (cddr index-item))))
1054 (apply function (car index-item) position rest))
1055 (run-hooks 'imenu-after-jump-hook)))
1057 (dolist (mess
1058 '("^No items suitable for an index found in this buffer$"
1059 "^This buffer cannot use `imenu-default-create-index-function'$"
1060 "^The mode `.*' does not support Imenu$"))
1061 (add-to-list 'debug-ignored-errors mess))
1063 (provide 'imenu)
1065 ;;; arch-tag: 98a2f5f5-4b91-4704-b18c-3aacf77d77a7
1066 ;;; imenu.el ends here