X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/2846c6e3607995ce250435e5998ea6a08f60dd89..70041e9ae7072eac5eeff2b5e1a50d9eab6b39f7:/lisp/imenu.el diff --git a/lisp/imenu.el b/lisp/imenu.el index 8573486b5a..cf055b3855 100644 --- a/lisp/imenu.el +++ b/lisp/imenu.el @@ -1,7 +1,7 @@ ;;; imenu.el --- framework for mode-specific buffer indexes ;; Copyright (C) 1994, 1995, 1996, 1997, 1998, 2001, 2002, 2003, 2004, -;; 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +;; 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. ;; Author: Ake Stenhoff ;; Lars Lindberg @@ -76,7 +76,7 @@ :link '(custom-manual "(elisp)Imenu")) (defcustom imenu-use-markers t - "*Non-nil means use markers instead of integers for Imenu buffer positions. + "Non-nil means use markers instead of integers for Imenu buffer positions. Setting this to nil makes Imenu work a little faster but editing the buffer will make the generated index positions wrong. @@ -87,18 +87,18 @@ This might not yet be honored by all index-building functions." (defcustom imenu-max-item-length 60 - "*If a number, truncate Imenu entries to that length." + "If a number, truncate Imenu entries to that length." :type '(choice integer (const :tag "Unlimited")) :group 'imenu) (defcustom imenu-auto-rescan nil - "*Non-nil means Imenu should always rescan the buffers." + "Non-nil means Imenu should always rescan the buffers." :type 'boolean :group 'imenu) (defcustom imenu-auto-rescan-maxout 60000 - "*Imenu auto-rescan is disabled in buffers larger than this size (in bytes). + "Imenu auto-rescan is disabled in buffers larger than this size (in bytes). This variable is buffer-local." :type 'integer :group 'imenu) @@ -128,7 +128,7 @@ If `on-mouse' use a popup menu when `imenu' was invoked with the mouse." :version "22.1") (defcustom imenu-after-jump-hook nil - "*Hooks called after jumping to a place in the buffer. + "Hooks called after jumping to a place in the buffer. Useful things to use here include `reposition-window', `recenter', and \(lambda () (recenter 0)) to show at top of screen." @@ -137,7 +137,7 @@ Useful things to use here include `reposition-window', `recenter', and ;;;###autoload (defcustom imenu-sort-function nil - "*The function to use for sorting the index mouse-menu. + "The function to use for sorting the index mouse-menu. Affects only the mouse index menu. @@ -156,13 +156,13 @@ element should come before the second. The arguments are cons cells; :group 'imenu) (defcustom imenu-max-items 25 - "*Maximum number of elements in a mouse menu for Imenu." + "Maximum number of elements in a mouse menu for Imenu." :type 'integer :group 'imenu) ;; No longer used. KFS 2004-10-27 ;; (defcustom imenu-scanning-message "Scanning buffer for index (%3d%%)" -;; "*Progress message during the index scanning of the buffer. +;; "Progress message during the index scanning of the buffer. ;; If non-nil, user gets a message during the scanning of the buffer. ;; ;; Relevant only if the mode-specific function that creates the buffer @@ -173,14 +173,14 @@ element should come before the second. The arguments are cons cells; ;; :group 'imenu) (defcustom imenu-space-replacement "." - "*The replacement string for spaces in index names. + "The replacement string for spaces in index names. Used when presenting the index in a completion buffer to make the names work as tokens." :type '(choice string (const nil)) :group 'imenu) (defcustom imenu-level-separator ":" - "*The separator between index names of different levels. + "The separator between index names of different levels. Used for making mouse-menu titles and for flattening nested indexes with name concatenation." :type 'string @@ -198,6 +198,7 @@ For example, see the value of `fortran-imenu-generic-expression' used by `fortran-mode' with `imenu-syntax-alist' set locally to give the characters which normally have \"symbol\" syntax \"word\" syntax during matching.") +;;;###autoload(put 'imenu-generic-expression 'risky-local-variable t) ;;;###autoload (make-variable-buffer-local 'imenu-generic-expression) @@ -297,9 +298,9 @@ The function in this variable is called when selecting a normal index-item.") ;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; FIXME: This is the only imenu-example-* definition that's actually used, -;; and it seems to only be used by cperl-mode.el. We should just move it to -;; cperl-mode.el and remove the rest. +;; FIXME: This was the only imenu-example-* definition actually used, +;; by cperl-mode.el. Now cperl-mode has its own copy, so these can +;; all be removed. (defun imenu-example--name-and-position () "Return the current/previous sexp and its (beginning) location. Don't move point." @@ -310,6 +311,8 @@ Don't move point." (end (progn (forward-sexp) (point)))) (cons (buffer-substring beg end) beg)))) +(make-obsolete 'imenu-example--name-and-position + "use your own function instead." "23.2") ;;; ;;; Lisp @@ -328,6 +331,7 @@ Don't move point." (end (progn (forward-sexp -1) (point)))) (buffer-substring beg end))) (error nil))))) +(make-obsolete 'imenu-example--lisp-extract-index-name "your own" "23.2") (defun imenu-example--create-lisp-index () ;; Example of a candidate for `imenu-create-index-function'. @@ -379,6 +383,7 @@ Don't move point." (push (cons "Syntax-unknown" index-unknown-alist) index-alist)) index-alist)) +(make-obsolete 'imenu-example--create-lisp-index "your own" "23.2") ;; Regular expression to find C functions (defvar imenu-example--function-name-regexp-c @@ -410,7 +415,7 @@ Don't move point." (push (imenu-example--name-and-position) index-alist)))) (imenu-progress-message prev-pos 100) (nreverse index-alist))) - +(make-obsolete 'imenu-example--create-c-index "your own" "23.2") ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; @@ -440,6 +445,7 @@ if it is a sub-alist. There is one simple element with negative POSITION; selecting that element recalculates the buffer's index alist.") +;;;###autoload(put 'imenu--index-alist 'risky-local-variable t) (make-variable-buffer-local 'imenu--index-alist) @@ -483,6 +489,8 @@ element recalculates the buffer's index alist.") ;; Split LIST into sublists of max length N. ;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8)) +;; +;; The returned list DOES NOT share structure with LIST. (defun imenu--split (list n) (let ((remain list) (result '()) @@ -504,10 +512,15 @@ element recalculates the buffer's index alist.") ;;; Split the alist MENULIST into a nested alist, if it is long enough. ;;; In any case, add TITLE to the front of the alist. +;;; If IMENU--RESCAN-ITEM is present in MENULIST, it is moved to the +;;; beginning of the returned alist. +;;; +;;; The returned alist DOES NOT share structure with MENULIST. (defun imenu--split-menu (menulist title) - (let (keep-at-top tail) + (let ((menulist (copy-sequence menulist)) + keep-at-top tail) (if (memq imenu--rescan-item menulist) - (setq keep-at-top (cons imenu--rescan-item nil) + (setq keep-at-top (list imenu--rescan-item) menulist (delq imenu--rescan-item menulist))) (setq tail menulist) (dolist (item tail) @@ -515,7 +528,7 @@ element recalculates the buffer's index alist.") (push item keep-at-top) (setq menulist (delq item menulist)))) (if imenu-sort-function - (setq menulist (sort (copy-sequence menulist) imenu-sort-function))) + (setq menulist (sort menulist imenu-sort-function))) (if (> (length menulist) imenu-max-items) (setq menulist (mapcar @@ -527,6 +540,9 @@ element recalculates the buffer's index alist.") ;;; Split up each long alist that are nested within ALIST ;;; into nested alists. +;;; +;;; Return a split and sorted copy of ALIST. The returned alist DOES +;;; NOT share structure with ALIST. (defun imenu--split-submenus (alist) (mapcar (function (lambda (elt) @@ -580,7 +596,7 @@ See `imenu--index-alist' for the format of the index alist." ;;; Find all markers in alist and makes ;;; them point nowhere. ;;; The top-level call uses nil as the argument; -;;; non-nil arguments are in recursivecalls. +;;; non-nil arguments are in recursive calls. (defvar imenu--cleanup-seen) (defun imenu--cleanup (&optional alist) @@ -655,7 +671,7 @@ and speed-up matching.") (make-variable-buffer-local 'imenu-syntax-alist) (defun imenu-default-create-index-function () - "*Default function to create an index alist of the current buffer. + "Default function to create an index alist of the current buffer. The most general method is to move point to end of buffer, then repeatedly call `imenu-prev-index-position-function' and `imenu-extract-index-name-function'. @@ -668,12 +684,15 @@ The alternate method, which is the one most often used, is to call ;; in these major modes. But save that change for later. (cond ((and imenu-prev-index-position-function imenu-extract-index-name-function) - (let ((index-alist '()) + (let ((index-alist '()) (pos (point)) prev-pos name) (goto-char (point-max)) (imenu-progress-message prev-pos 0 t) ;; Search for the function (while (funcall imenu-prev-index-position-function) + (when (= pos (point)) + (error "Infinite loop at %s:%d: imenu-prev-index-position-function does not move point" (buffer-name) pos)) + (setq pos (point)) (imenu-progress-message prev-pos nil t) (save-excursion (setq name (funcall imenu-extract-index-name-function)))