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