lisp/imenu.el

   1 ;;; imenu.el --- Framework for mode-specific buffer indexes.
   2
   3 ;; Copyright (C) 1994, 1995 Free Software Foundation, Inc.
   4
   5 ;; Author: Ake Stenhoff <etxaksf@aom.ericsson.se>
   6 ;;         Lars Lindberg <lli@sypro.cap.se>
   7 ;; Created: 8 Feb 1994
   8 ;; Keywords: tools
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28
  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 ;; How it works:
  35
  36 ;;   A mode-specific function is called to generate the index.  It is
  37 ;;   then presented to the user, who can choose from this index.
  38 ;;
  39 ;;   The package comes with a set of example functions for how to
  40 ;;   utilize this package.
  41
  42 ;;   There are *examples* for index gathering functions/regular
  43 ;;   expressions for C/C++ and Lisp/Emacs Lisp but it is easy to
  44 ;;   customize for other modes.  A function for jumping to the chosen
  45 ;;   index position is also supplied.
  46
  47 ;;; Thanks goes to
  48 ;;  [simon] - Simon Leinen simon@lia.di.epfl.ch
  49 ;;  [dean] - Dean Andrews ada@unison.com
  50 ;;  [alon] - Alon Albert al@mercury.co.il
  51 ;;  [greg] - Greg Thompson gregt@porsche.visix.COM
  52 ;;  [wolfgang] - Wolfgang Bangerth zcg51122@rpool1.rus.uni-stuttgart.de
  53 ;;  [kai] - Kai Grossjohann grossjoh@linus.informatik.uni-dortmund.de
  54 ;;  [david] - David M. Smith dsmith@stats.adelaide.edu.au
  55 ;;  [christian] - Christian Egli Christian.Egli@hcsd.hac.com
  56 ;;  [karl] - Karl Fogel kfogel@floss.life.uiuc.edu
  57
  58 ;;; Code
  59
  60 (eval-when-compile (require 'cl))
  61
  62 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  63 ;;;
  64 ;;; Customizable variables
  65 ;;;
  66 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  67 (defvar imenu-use-keymap-menu nil
  68   "*Non-nil means use a keymap when making the mouse menu.")
  69
  70 (defvar imenu-auto-rescan nil
  71   "*Non-nil means Imenu should always rescan the buffers.")
  72
  73 (defvar imenu-auto-rescan-maxout 60000
  74   "* auto-rescan is disabled in buffers larger than this.
  75 This variable is buffer-local.")
  76
  77 (defvar imenu-always-use-completion-buffer-p nil
  78   "*Set this to non-nil for displaying the index in a completion buffer.
  79
  80 Non-nil means always display the index in a completion buffer.
  81 Nil means display the index as a mouse menu when the mouse was
  82 used to invoke `imenu'.
  83 `never' means never automatically display a listing of any kind.")
  84
  85 (defvar imenu-sort-function nil
  86   "*The function to use for sorting the index mouse-menu.
  87
  88 Affects only the mouse index menu.
  89
  90 Set this to nil if you don't want any sorting (faster).
  91 The items in the menu are then presented in the order they were found
  92 in the buffer.
  93
  94 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
  95
  96 The function should take two arguments and return T if the first
  97 element should come before the second.  The arguments are cons cells;
  98 \(NAME . POSITION).  Look at `imenu--sort-by-name' for an example.")
  99
 100 (defvar imenu-max-items 25
 101   "*Maximum number of elements in an index mouse-menu.")
 102
 103 (defvar imenu-scanning-message "Scanning buffer for index (%3d%%)"
 104   "*Progress message during the index scanning of the buffer.
 105 If non-nil, user gets a message during the scanning of the buffer
 106
 107 Relevant only if the mode-specific function that creates the buffer
 108 index use `imenu-progress-message'.")
 109
 110 (defvar imenu-space-replacement "^"
 111   "*The replacement string for spaces in index names.
 112 Used when presenting the index in a completion-buffer to make the
 113 names work as tokens.")
 114
 115 (defvar imenu-level-separator ":"
 116   "*The separator between index names of different levels.
 117 Used for making mouse-menu titles and for flattening nested indexes
 118 with name concatenation.")
 119
 120 (defvar imenu-submenu-name-format "%s"
 121   "*The format for making a submenu name.")
 122
 123 ;;;###autoload
 124 (defvar imenu-generic-expression nil
 125   "The regex pattern to use for creating a buffer index.
 126
 127 If non-nil this pattern is passed to `imenu-create-index-with-pattern'
 128 to create a buffer index.
 129
 130 It is an alist with elements that look like this: (MENU-TITLE
 131 REGEXP INDEX).
 132
 133 MENU-TITLE is a string used as the title for the submenu or nil if the
 134 entries are not nested.
 135
 136 REGEXP is a regexp that should match a construct in the buffer that is
 137 to be displayed in the menu; i.e., function or variable definitions,
 138 etc.  It contains a substring which is the name to appear in the
 139 menu.  See the info section on Regexps for more information.
 140
 141 INDEX points to the substring in REGEXP that contains the name (of the
 142 function, variable or type) that is to appear in the menu.
 143
 144 For emacs-lisp-mode for example PATTERN would look like:
 145
 146 '((nil \"^\\\\s-*(def\\\\(un\\\\|subst\\\\|macro\\\\|advice\\\\)\\\\s-+\\\\([-A-Za-z0-9+]+\\\\)\" 2)
 147   (\"*Vars*\" \"^\\\\s-*(def\\\\(var\\\\|const\\\\)\\\\s-+\\\\([-A-Za-z0-9+]+\\\\)\" 2)
 148   (\"*Types*\" \"^\\\\s-*(def\\\\(type\\\\|struct\\\\|class\\\\|ine-condition\\\\)\\\\s-+\\\\([-A-Za-z0-9+]+\\\\)\" 2))
 149
 150 The variable is buffer-local.")
 151
 152 (make-variable-buffer-local 'imenu-generic-expression)
 153
 154 ;;;; Hooks
 155
 156 (defvar imenu-create-index-function 'imenu-default-create-index-function
 157   "The function to use for creating a buffer index.
 158
 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).
 163
 164 This function is called within a `save-excursion'.
 165
 166 The variable is buffer-local.")
 167 (make-variable-buffer-local 'imenu-create-index-function)
 168
 169 (defvar imenu-prev-index-position-function 'beginning-of-defun
 170   "Function for finding the next index position.
 171
 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
 175 file.
 176
 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 'imenu-prev-index-position-function)
 180
 181 (defvar imenu-extract-index-name-function nil
 182   "Function for extracting the index name.
 183
 184 This function is called after the function pointed out by
 185 `imenu-prev-index-position-function'.")
 186 (make-variable-buffer-local 'imenu-extract-index-name-function)
 187
 188 ;;;
 189 ;;; Macro to display a progress message.
 190 ;;; RELPOS is the relative position to display.
 191 ;;; If RELPOS is nil, then the relative position in the buffer
 192 ;;; is calculated.
 193 ;;; PREVPOS is the variable in which we store the last position displayed.
 194 (defmacro imenu-progress-message (prevpos &optional relpos reverse)
 195   (` (and
 196       imenu-scanning-message
 197       (let ((pos (, (if relpos
 198                         relpos
 199                       (` (imenu--relative-position (, reverse)))))))
 200         (if (, (if relpos t
 201                  (` (> pos (+ 5 (, prevpos))))))
 202             (progn
 203               (message imenu-scanning-message pos)
 204               (setq (, prevpos) pos)))))))
 205
 206
 207 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 208 ;;;;
 209 ;;;; Some examples of functions utilizing the framework of this
 210 ;;;; package.
 211 ;;;;
 212 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 213
 214 ;; Return the current/previous sexp and the location of the sexp (its
 215 ;; beginning) without moving the point.
 216 (defun imenu-example--name-and-position ()
 217   (save-excursion
 218     (forward-sexp -1)
 219     (let ((beg (point))
 220           (end (progn (forward-sexp) (point)))
 221           (marker (make-marker)))
 222       (set-marker marker beg)
 223       (cons (buffer-substring beg end)
 224             marker))))
 225
 226 ;;;
 227 ;;; Lisp
 228 ;;;
 229
 230 (defun imenu-example--lisp-extract-index-name ()
 231   ;; Example of a candidate for `imenu-extract-index-name-function'.
 232   ;; This will generate a flat index of definitions in a lisp file.
 233   (save-match-data
 234     (and (looking-at "(def")
 235          (condition-case nil
 236              (progn
 237                (down-list 1)
 238                (forward-sexp 2)
 239                (let ((beg (point))
 240                      (end (progn (forward-sexp -1) (point))))
 241                  (buffer-substring beg end)))
 242            (error nil)))))
 243
 244 (defun imenu-example--create-lisp-index ()
 245   ;; Example of a candidate for `imenu-create-index-function'.
 246   ;; It will generate a nested index of definitions.
 247   (let ((index-alist '())
 248         (index-var-alist '())
 249         (index-type-alist '())
 250         (index-unknown-alist '())
 251         prev-pos)
 252     (goto-char (point-max))
 253     (imenu-progress-message prev-pos 0)
 254     ;; Search for the function
 255     (while (beginning-of-defun)
 256       (imenu-progress-message prev-pos nil t)
 257       (save-match-data
 258         (and (looking-at "(def")
 259              (save-excursion
 260                (down-list 1)
 261                (cond
 262                 ((looking-at "def\\(var\\|const\\)")
 263                  (forward-sexp 2)
 264                  (push (imenu-example--name-and-position)
 265                        index-var-alist))
 266                 ((looking-at "def\\(un\\|subst\\|macro\\|advice\\)")
 267                  (forward-sexp 2)
 268                  (push (imenu-example--name-and-position)
 269                        index-alist))
 270                 ((looking-at "def\\(type\\|struct\\|class\\|ine-condition\\)")
 271                  (forward-sexp 2)
 272                  (if (= (char-after (1- (point))) ?\))
 273                      (progn
 274                        (forward-sexp -1)
 275                        (down-list 1)
 276                        (forward-sexp 1)))
 277                  (push (imenu-example--name-and-position)
 278                        index-type-alist))
 279                 (t
 280                  (forward-sexp 2)
 281                  (push (imenu-example--name-and-position)
 282                        index-unknown-alist)))))))
 283     (imenu-progress-message prev-pos 100)
 284     (and index-var-alist
 285          (push (cons (imenu-create-submenu-name "Variables") index-var-alist)
 286                index-alist))
 287     (and index-type-alist
 288          (push (cons (imenu-create-submenu-name "Types") index-type-alist)
 289                index-alist))
 290     (and index-unknown-alist
 291          (push (cons (imenu-create-submenu-name "Syntax-unknown") index-unknown-alist)
 292                index-alist))
 293     index-alist))
 294
 295 ;; Regular expression to find C functions
 296 (defvar imenu-example--function-name-regexp-c
 297   (concat
 298    "^[a-zA-Z0-9]+[ \t]?"                ; type specs; there can be no
 299    "\\([a-zA-Z0-9_*]+[ \t]+\\)?"        ; more than 3 tokens, right?
 300    "\\([a-zA-Z0-9_*]+[ \t]+\\)?"
 301    "\\([*&]+[ \t]*\\)?"                 ; pointer
 302    "\\([a-zA-Z0-9_*]+\\)[ \t]*("        ; name
 303    ))
 304
 305 (defun imenu-example--create-c-index (&optional regexp)
 306   (let ((index-alist '())
 307         prev-pos char)
 308     (goto-char (point-min))
 309     (imenu-progress-message prev-pos 0)
 310     ;; Search for the function
 311     (save-match-data
 312       (while (re-search-forward
 313               (or regexp imenu-example--function-name-regexp-c)
 314               nil t)
 315         (imenu-progress-message prev-pos)
 316         (backward-up-list 1)
 317         (save-excursion
 318           (goto-char (scan-sexps (point) 1))
 319           (setq char (following-char)))
 320         ;; Skip this function name if it is a prototype declaration.
 321         (if (not (eq char ?\;))
 322             (push (imenu-example--name-and-position) index-alist))))
 323     (imenu-progress-message prev-pos 100)
 324     (nreverse index-alist)))
 325
 326
 327 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 328 ;;;
 329 ;;; Internal variables
 330 ;;;
 331 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 332
 333 ;; The item to use in the index for rescanning the buffer.
 334 (defconst imenu--rescan-item '("*Rescan*" . -99))
 335
 336 ;; The latest buffer index.
 337 ;; Buffer local.
 338 (defvar imenu--index-alist nil)
 339 (make-variable-buffer-local 'imenu--index-alist)
 340
 341 ;; The latest buffer index used to update the menu bar menu.
 342 (defvar imenu--last-menubar-index-alist nil)
 343 (make-variable-buffer-local 'imenu--last-menubar-index-alist)
 344
 345 ;; History list for 'jump-to-function-in-buffer'.
 346 ;; Making this buffer local caused it not to work!
 347 (defvar imenu--history-list nil)
 348
 349 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 350 ;;;
 351 ;;; Internal support functions
 352 ;;;
 353 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 354
 355 ;;;
 356 ;;; Sort function
 357 ;;; Sorts the items depending on their index name.
 358 ;;; An item look like (NAME . POSITION).
 359 ;;;
 360 (defun imenu--sort-by-name (item1 item2)
 361   (string-lessp (car item1) (car item2)))
 362
 363 (defun imenu--relative-position (&optional reverse)
 364   ;; Support function to calculate relative position in buffer
 365   ;; Beginning of buffer is 0 and end of buffer is 100
 366   ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
 367   (let ((pos (point))
 368         (total (buffer-size)))
 369     (and reverse (setq pos (- total pos)))
 370     (if (> total 50000)
 371         ;; Avoid overflow from multiplying by 100!
 372         (/ (1- pos) (max (/ total 100) 1))
 373       (/ (* 100 (1- pos)) (max total 1)))))
 374
 375 ;;;
 376 ;;; Function for supporting general looking submenu names.
 377 ;;; Uses `imenu-submenu-name-format' for creating the name.
 378 ;;; NAME is the base of the new submenu name.
 379 ;;;
 380 (defun imenu-create-submenu-name (name)
 381    (format imenu-submenu-name-format name))
 382
 383 ;; Split LIST into sublists of max length N.
 384 ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
 385 (defun imenu--split (list n)
 386   (let ((remain list)
 387         (result '())
 388         (sublist '())
 389         (i 0))
 390     (while remain
 391       (push (pop remain) sublist)
 392       (incf i)
 393       (and (= i n)
 394            ;; We have finished a sublist
 395            (progn (push (nreverse sublist) result)
 396                   (setq i 0)
 397                   (setq sublist '()))))
 398     ;; There might be a sublist (if the length of LIST mod n is != 0)
 399     ;; that has to be added to the result list.
 400     (and sublist
 401          (push (nreverse sublist) result))
 402     (nreverse result)))
 403
 404 ;;;
 405 ;;; Split a menu in to several menus.
 406 ;;;
 407 (defun imenu--split-menu (menulist title)
 408   (cons "Index menu"
 409         (mapcar
 410          (function
 411           (lambda (menu)
 412             (cons (format "(%s)" title) menu)))
 413          (imenu--split menulist imenu-max-items))))
 414
 415 ;;;
 416 ;;; Find all items in this buffer that should be in the index.
 417 ;;; Returns an alist on the form
 418 ;;; ((NAME . POSITION) (NAME . POSITION) ...)
 419 ;;;
 420
 421 (defun imenu--make-index-alist (&optional noerror)
 422   ;; Create a list for this buffer only when needed.
 423   (or (and imenu--index-alist
 424            (or (not imenu-auto-rescan)
 425                (and imenu-auto-rescan
 426                     (> (buffer-size)  imenu-auto-rescan-maxout))))
 427       ;; Get the index
 428       (setq imenu--index-alist
 429             (save-excursion
 430               (funcall imenu-create-index-function))))
 431   (or imenu--index-alist noerror
 432       (error "No items suitable for an index found in this buffer"))
 433   (or imenu--index-alist
 434       (setq imenu--index-alist (list nil)))
 435   ;; Add a rescan option to the index.
 436   (cons imenu--rescan-item imenu--index-alist))
 437 ;;;
 438 ;;; Find all markers in alist and makes
 439 ;;; them point nowhere.
 440 ;;;
 441 (defun imenu--cleanup (&optional alist)
 442   ;; Sets the markers in imenu--index-alist
 443   ;; point nowhere.
 444   ;; if alist is provided use that list.
 445   (or alist
 446       (setq alist imenu--index-alist))
 447   (and alist
 448        (mapcar
 449         (function
 450          (lambda (item)
 451            (cond
 452             ((markerp (cdr item))
 453              (set-marker (cdr item) nil))
 454             ((consp (cdr item))
 455              (imenu--cleanup (cdr item))))))
 456         alist)
 457        t))
 458
 459 (defun imenu--create-keymap-2 (alist counter &optional commands)
 460   (let ((map nil))
 461     (mapcar
 462      (function
 463       (lambda (item)
 464         (cond
 465          ((listp (cdr item))
 466           (append (list (setq counter (1+ counter))
 467                         (car item) 'keymap (car item))
 468                   (imenu--create-keymap-2 (cdr item) (+ counter 10) commands)))
 469          (t
 470           (let ((end (if commands `(lambda () (interactive)
 471                                      (imenu--menubar-select ',item))
 472                        (cons '(nil) t))))
 473             (cons (car item)
 474                   (cons (car item) end))))
 475          )))
 476      alist)))
 477
 478 ;; If COMMANDS is non-nil, make a real keymap
 479 ;; with a real command used as the definition.
 480 ;; If it is nil, make something suitable for x-popup-menu.
 481 (defun imenu--create-keymap-1 (title alist &optional commands)
 482   (append (list 'keymap title) (imenu--create-keymap-2 alist 0 commands)))
 483
 484
 485 (defun imenu--in-alist (str alist)
 486   "Check whether the string STR is contained in multi-level ALIST."
 487   (let (elt head tail res)
 488     (setq res nil)
 489     (while alist
 490       (setq elt (car alist)
 491             tail (cdr elt)
 492             alist (cdr alist)
 493             head (car elt))
 494       (if (string= str head)
 495           (setq alist nil res elt)
 496         (if (and (listp tail)
 497                  (setq res (imenu--in-alist str tail)))
 498             (setq alist nil))))
 499     res))
 500
 501 (defun imenu-default-create-index-function ()
 502   "*Wrapper for index searching functions.
 503
 504 Moves point to end of buffer and then repeatedly calls
 505 `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
 506 Their results are gathered into an index alist."
 507   ;; These should really be done by setting imenu-create-index-function
 508   ;; in these major modes.  But save that change for later.
 509   (cond ((and (fboundp imenu-prev-index-position-function)
 510               (fboundp imenu-extract-index-name-function))
 511          (let ((index-alist '())
 512                prev-pos name)
 513            (goto-char (point-max))
 514            (imenu-progress-message prev-pos 0 t)
 515            ;; Search for the function
 516            (while (funcall imenu-prev-index-position-function)
 517              (imenu-progress-message prev-pos nil t)
 518              (save-excursion
 519                (setq name (funcall imenu-extract-index-name-function)))
 520              (and (stringp name)
 521                   (push (cons name (point)) index-alist)))
 522            (imenu-progress-message prev-pos 100 t)
 523            index-alist))
 524         ;; Use generic expression if possible.
 525         ((and imenu-generic-expression)
 526          (imenu--generic-function imenu-generic-expression))
 527         (t
 528          (error "The mode \"%s\" does not take full advantage of imenu.el yet."
 529                 mode-name))))
 530
 531 (defun imenu--replace-spaces (name replacement)
 532   ;; Replace all spaces in NAME with REPLACEMENT.
 533   ;; That second argument should be a string.
 534   (mapconcat
 535    (function
 536     (lambda (ch)
 537       (if (char-equal ch ?\ )
 538           replacement
 539         (char-to-string ch))))
 540    name
 541    ""))
 542
 543 (defun imenu--flatten-index-alist (index-alist &optional concat-names prefix)
 544   ;; Takes a nested INDEX-ALIST and returns a flat index alist.
 545   ;; If optional CONCAT-NAMES is non-nil, then a nested index has its
 546   ;; name and a space concatenated to the names of the children.
 547   ;; Third argument PREFIX is for internal use only.
 548   (mapcan
 549    (function
 550     (lambda (item)
 551       (let* ((name (car item))
 552              (pos (cdr item))
 553              (new-prefix (and concat-names
 554                               (if prefix
 555                                   (concat prefix imenu-level-separator name)
 556                                 name))))
 557         (cond
 558          ((or (markerp pos) (numberp pos))
 559           (list (cons new-prefix pos)))
 560          (t
 561           (imenu--flatten-index-alist pos new-prefix))))))
 562    index-alist))
 563
 564 ;;;
 565 ;;; Generic index gathering function.
 566 ;;;
 567
 568 (defun imenu--generic-function (patterns)
 569 ;; Built on some ideas that Erik Naggum <erik@naggum.no> once posted
 570 ;; to comp.emacs
 571   "Return an index of the current buffer as an alist.
 572
 573 PATTERN is an alist with elements that look like this: (MENU-TITLE
 574 REGEXP INDEX).
 575
 576 MENU-TITLE is a string used as the title for the submenu or nil if the
 577 entries are not nested.
 578
 579 REGEXP is a regexp that should match a construct in the buffer that is
 580 to be displayed in the menu; i.e., function or variable definitions,
 581 etc.  It contains a substring which is the name to appear in the
 582 menu.  See the info section on Regexps for more information.
 583
 584 INDEX points to the substring in REGEXP that contains the name (of the
 585 function, variable or type) that is to appear in the menu.
 586
 587 For emacs-lisp-mode for example PATTERN would look like:
 588
 589 '((nil \"^\\\\s-*(def\\\\(un\\\\|subst\\\\|macro\\\\|advice\\\\)\\\\s-+\\\\([-A-Za-z0-9]+\\\\)\" 2)
 590   (\"*Vars*\" \"^\\\\s-*(def\\\\(var\\\\|const\\\\)\\\\s-+\\\\([-A-Za-z0-9]+\\\\)\" 2)
 591   (\"*Types*\" \"^\\\\s-*(def\\\\(type\\\\|struct\\\\|class\\\\|ine-condition\\\\)\\\\s-+\\\\([-A-Za-z0-9]+\\\\)\" 2))'
 592
 593 Returns an index of the current buffer as an alist.  The elements in
 594 the alist look like: (INDEX-NAME . INDEX-POSITION).  They may also be
 595 nested index lists like (INDEX-NAME . INDEX-ALIST) depending on
 596 pattern.
 597
 598 \(imenu--generic-function PATTERN\)."
 599
 600   (let ((index-alist (list 'dummy))
 601         (found nil)
 602         (global-regexp
 603          (concat "\\("
 604                  (mapconcat
 605                   (function (lambda (pattern) (identity (cadr pattern))))
 606                   patterns "\\)\\|\\(")
 607                  "\\)"))
 608         prev-pos)
 609
 610     (goto-char (point-max))
 611     (imenu-progress-message prev-pos 0 t)
 612     (save-match-data
 613       (while (re-search-backward global-regexp nil t)
 614         (imenu-progress-message prev-pos nil t)
 615         (setq found nil)
 616         (save-excursion
 617           (goto-char (match-beginning 0))
 618           (mapcar
 619            (function
 620             (lambda (pat)
 621               (let ((menu-title (car pat))
 622                     (regexp (cadr pat))
 623                     (index (caddr pat)))
 624                     (if (and (not found) ; Only allow one entry;
 625                              (looking-at regexp))
 626                         (let ((beg (match-beginning index))
 627                               (end (match-end index)))
 628                           (setq found t)
 629                           (push
 630                            (cons (buffer-substring-no-properties beg end) beg)
 631                            (cdr
 632                             (or (if (not (stringp menu-title)) index-alist)
 633                                 (assoc
 634                                  (imenu-create-submenu-name menu-title)
 635                                  index-alist)
 636                                 (car (push
 637                                       (cons
 638                                        (imenu-create-submenu-name menu-title)
 639                                        '())
 640                                       index-alist))))))))))
 641             patterns))))
 642       (imenu-progress-message prev-pos 100 t)
 643       (delete 'dummy index-alist)))
 644
 645 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 646 ;;;
 647 ;;; The main functions for this package!
 648 ;;;
 649 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 650
 651 (defun imenu--completion-buffer (index-alist &optional prompt)
 652   "Let the user select from INDEX-ALIST in a completion buffer with PROMPT.
 653
 654 Returns t for rescan and otherwise a position number."
 655   ;; Create a list for this buffer only when needed.
 656   (let (name choice
 657              (prepared-index-alist
 658               (mapcar
 659                (function
 660                 (lambda (item)
 661                   (cons (imenu--replace-spaces (car item) imenu-space-replacement)
 662                         (cdr item))))
 663                index-alist)))
 664     (if (eq imenu-always-use-completion-buffer-p 'never)
 665         (setq name (completing-read (or prompt "Index item: ")
 666                                     prepared-index-alist
 667                                     nil t nil 'imenu--history-list))
 668       (save-window-excursion
 669         ;; Display the completion buffer
 670         (with-output-to-temp-buffer "*Completions*"
 671           (display-completion-list
 672            (all-completions "" prepared-index-alist )))
 673         (let ((minibuffer-setup-hook
 674                (function (lambda ()
 675                            (let ((buffer (current-buffer)))
 676                              (save-excursion
 677                                (set-buffer "*Completions*")
 678                                (setq completion-reference-buffer buffer)))))))
 679           ;; Make a completion question
 680           (setq name (completing-read (or prompt "Index item: ")
 681                                       prepared-index-alist
 682                                       nil t nil 'imenu--history-list)))))
 683     (cond ((not (stringp name))
 684            nil)
 685           ((string= name (car imenu--rescan-item))
 686            t)
 687           (t
 688            (setq choice (assoc name prepared-index-alist))
 689            (if (listp (cdr choice))
 690                (imenu--completion-buffer (cdr choice) prompt)
 691              choice)))))
 692
 693 (defun imenu--mouse-menu (index-alist event &optional title)
 694   "Let the user select from a buffer index from a mouse menu.
 695
 696 INDEX-ALIST is the buffer index and EVENT is a mouse event.
 697
 698 Returns t for rescan and otherwise a position number."
 699   (let* ((menu  (imenu--split-menu
 700                  (if imenu-sort-function
 701                      (sort
 702                       (let ((res nil)
 703                             (oldlist index-alist))
 704                         ;; Copy list method from the cl package `copy-list'
 705                         (while (consp oldlist) (push (pop oldlist) res))
 706                         (prog1 (nreverse res) (setcdr res oldlist)))
 707                       imenu-sort-function)
 708                    index-alist)
 709                  (or title (buffer-name))))
 710          position)
 711     (and imenu-use-keymap-menu
 712          (setq menu (imenu--create-keymap-1 (car menu)
 713                                             (if (< 1 (length (cdr menu)))
 714                                                 (cdr menu)
 715                                               (cdr (cadr menu))))))
 716     (setq position (x-popup-menu event menu))
 717     (if imenu-use-keymap-menu
 718         (progn
 719           (cond
 720            ((and (listp position)
 721                  (numberp (car position))
 722                  (stringp (nth (1- (length position)) position)))
 723             (setq position (nth (1- (length position)) position)))
 724            ((and (stringp (car position))
 725                  (null (cdr position)))
 726             (setq position (car position))))))
 727     (cond
 728      ((eq position nil)
 729       position)
 730      ((listp position)
 731       (imenu--mouse-menu position event
 732                          (if title
 733                              (concat title imenu-level-separator
 734                                      (car (rassq position index-alist)))
 735                            (car (rassq position index-alist)))))
 736      ((stringp position)
 737       (or (string= position (car imenu--rescan-item))
 738           (imenu--in-alist position index-alist)))
 739      ((or (= position (cdr imenu--rescan-item))
 740           (and (stringp position)
 741                (string= position (car imenu--rescan-item))))
 742       t)
 743      (t
 744       (rassq position index-alist)))))
 745
 746 (defun imenu-choose-buffer-index (&optional prompt alist)
 747   "Let the user select from a buffer index and return the chosen index.
 748
 749 If the user originally activated this function with the mouse, a mouse
 750 menu is used.  Otherwise a completion buffer is used and the user is
 751 prompted with PROMPT.
 752
 753 If you call this function with index alist ALIST, then it lets the user
 754 select from ALIST.
 755
 756 With no index alist ALIST, it calls `imenu--make-index-alist' to
 757 create the index alist.
 758
 759 If `imenu-always-use-completion-buffer-p' is non-nil, then the
 760 completion buffer is always used, no matter if the mouse was used or
 761 not.
 762
 763 The returned value is on the form (INDEX-NAME . INDEX-POSITION)."
 764   (let (index-alist
 765         (mouse-triggered (listp last-nonmenu-event))
 766         (result t) )
 767     ;; If selected by mouse, see to that the window where the mouse is
 768     ;; really is selected.
 769     (and mouse-triggered
 770          (not (equal last-nonmenu-event '(menu-bar)))
 771          (let ((window (posn-window (event-start last-nonmenu-event))))
 772            (or (framep window) (null window) (select-window window))))
 773     ;; Create a list for this buffer only when needed.
 774     (while (eq result t)
 775       (setq index-alist (if alist alist (imenu--make-index-alist)))
 776       (setq result
 777             (if (and mouse-triggered
 778                      (not imenu-always-use-completion-buffer-p))
 779                 (imenu--mouse-menu index-alist last-nonmenu-event)
 780               (imenu--completion-buffer index-alist prompt)))
 781       (and (eq result t)
 782            (imenu--cleanup)
 783            (setq imenu--index-alist nil)))
 784     result))
 785
 786 ;;;###autoload
 787 (defun imenu-add-to-menubar (name)
 788   "Adds an `imenu' entry to the menu bar for the current buffer.
 789 NAME is a string used to name the menu bar item.
 790 See the command `imenu' for more information."
 791   (interactive "sImenu menu item name: ")
 792   (let ((newmap (make-sparse-keymap))
 793         (menu-bar (lookup-key (current-local-map) [menu-bar])))
 794     (define-key newmap [menu-bar]
 795       (append (make-sparse-keymap) menu-bar))
 796     (define-key newmap [menu-bar index]
 797       (cons name (nconc (make-sparse-keymap "Imenu")
 798                         (make-sparse-keymap))))
 799     (use-local-map (append newmap (current-local-map))))
 800   (add-hook 'menu-bar-update-hook 'imenu-update-menubar))
 801
 802 (defvar imenu-buffer-menubar nil)
 803
 804 (defun imenu-update-menubar ()
 805   (and (current-local-map)
 806        (keymapp (lookup-key (current-local-map) [menu-bar index]))
 807        (let ((index-alist (imenu--make-index-alist t)))
 808          ;; Don't bother updating if the index-alist has not changed
 809          ;; since the last time we did it.
 810          (or (equal index-alist imenu--last-menubar-index-alist)
 811              (let (menu menu1 old)
 812                (setq imenu--last-menubar-index-alist index-alist)
 813                (setq menu (imenu--split-menu
 814                            (if imenu-sort-function
 815                                (sort
 816                                 (let ((res nil)
 817                                       (oldlist index-alist))
 818                                   ;; Copy list method from the cl package `copy-list'
 819                                   (while (consp oldlist) (push (pop oldlist) res))
 820                                   (prog1 (nreverse res) (setcdr res oldlist)))
 821                                 imenu-sort-function)
 822                              index-alist)
 823                            (buffer-name)))
 824                (setq menu1 (imenu--create-keymap-1 (car menu)
 825                                                    (if (< 1 (length (cdr menu)))
 826                                                        (cdr menu)
 827                                                      (cdr (car (cdr menu))))
 828                                                    t))
 829                (setq old (lookup-key (current-local-map) [menu-bar index]))
 830                (if (keymapp old)
 831                    (setcdr (nthcdr 2 old) menu1)))))))
 832
 833 (defun imenu--menubar-select (item)
 834   "Use Imenu to select the function or variable named in this menu item."
 835   (interactive)
 836   (imenu item))
 837
 838 ;;;###autoload
 839 (defun imenu (index-item)
 840   "Jump to a place in the buffer chosen using a buffer menu or mouse menu.
 841 See `imenu-choose-buffer-index' for more information."
 842   (interactive
 843    (list (save-restriction
 844            (widen)
 845            (car (imenu-choose-buffer-index)))))
 846   ;; Convert a string to an alist element.
 847   (if (stringp index-item)
 848       (setq index-item (assoc index-item (imenu--make-index-alist))))
 849   (and index-item
 850        (progn
 851          (push-mark)
 852          (cond
 853           ((markerp (cdr index-item))
 854            (if (or ( > (marker-position (cdr index-item)) (point-min))
 855                    ( < (marker-position (cdr index-item)) (point-max)))
 856                ;; widen if outside narrowing
 857                (widen))
 858            (goto-char (marker-position (cdr index-item))))
 859           (t
 860            (if (or ( > (cdr index-item) (point-min))
 861                    ( < (cdr index-item) (point-max)))
 862                ;; widen if outside narrowing
 863                (widen))
 864            (goto-char (cdr index-item)))))))
 865
 866 (provide 'imenu)
 867
 868 ;;; imenu.el ends here