code.delx.au - gnu-emacs/blob - lisp/imenu.el

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