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