Lines Matching +defs:imenu +defs:add +defs:menubar +defs:index
0 ;;; imenu.el --- framework for mode-specific buffer indexes
33 ;; A buffer index is an alist of names and buffer positions.
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.
46 ;; There are *examples* for index gathering functions/regular
49 ;; index position is also supplied.
73 (defgroup imenu nil
80 (defcustom imenu-use-markers t
84 buffer will make the generated index positions wrong.
86 This might not yet be honored by all index-building functions."
88 :group 'imenu)
91 (defcustom imenu-max-item-length 60
95 :group 'imenu)
97 (defcustom imenu-auto-rescan nil
100 :group 'imenu)
102 (defcustom imenu-auto-rescan-maxout 60000
106 :group 'imenu)
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")
112 (defcustom imenu-use-popup-menu
113 (if imenu-always-use-completion-buffer-p
114 (not (eq imenu-always-use-completion-buffer-p 'never))
119 If `on-mouse' use a popup menu when `imenu' was invoked with the mouse."
123 :group 'imenu)
125 (defcustom imenu-eager-completion-buffer
126 (not (eq imenu-always-use-completion-buffer-p 'never))
129 :group 'imenu
132 (defcustom imenu-after-jump-hook nil
138 :group 'imenu)
141 (defcustom imenu-sort-function nil
142 "*The function to use for sorting the index mouse-menu.
144 Affects only the mouse index menu.
150 Set it to `imenu--sort-by-name' if you want alphabetic sorting.
154 \(NAME . POSITION). Look at `imenu--sort-by-name' for an example."
156 (const :tag "Sort by name" imenu--sort-by-name)
158 :group 'imenu)
160 (defcustom imenu-max-items 25
163 :group 'imenu)
166 ;; (defcustom imenu-scanning-message "Scanning buffer for index (%3d%%)"
167 ;; "*Progress message during the index scanning of the buffer.
171 ;; index use `imenu-progress-message', and not useful if that is fast, in
175 ;; :group 'imenu)
177 (defcustom imenu-space-replacement "."
178 "*The replacement string for spaces in index names.
179 Used when presenting the index in a completion buffer to make the
182 :group 'imenu)
184 (defcustom imenu-level-separator ":"
185 "*The separator between index names of different levels.
189 :group 'imenu)
192 (defvar imenu-generic-expression nil
193 "The regex pattern to use for creating a buffer index.
195 If non-nil this pattern is passed to `imenu--generic-function' to
196 create a buffer index. Look there for the documentation of this
199 For example, see the value of `fortran-imenu-generic-expression' used by
200 `fortran-mode' with `imenu-syntax-alist' set locally to give the
205 (make-variable-buffer-local 'imenu-generic-expression)
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.
214 an index alist of the current buffer. The function is
217 See `imenu--index-alist' for the format of the buffer index alist.")
219 (make-variable-buffer-local 'imenu-create-index-function)
222 (defvar imenu-prev-index-position-function 'beginning-of-defun
223 "Function for finding the next index position.
225 If `imenu-create-index-function' is set to
226 `imenu-default-create-index-function', then you must set this variable
227 to a function that will find the next index, looking backwards in the
231 index and it should return nil when it doesn't find another index.")
233 (make-variable-buffer-local 'imenu-prev-index-position-function)
236 (defvar imenu-extract-index-name-function nil
237 "Function for extracting the index item name, given a position.
239 This function is called after `imenu-prev-index-position-function'
240 finds a position for an index item, with point at that position.
241 It should return the name for that index item.")
243 (make-variable-buffer-local 'imenu-extract-index-name-function)
246 (defvar imenu-name-lookup-function nil
247 "Function to compare string with index item.
257 (make-variable-buffer-local 'imenu-name-lookup-function)
260 (defvar imenu-default-goto-function 'imenu-default-goto-function
262 The function in this variable is called when selecting a normal index-item.")
264 (make-variable-buffer-local 'imenu-default-goto-function)
267 (defun imenu--subalist-p (item)
276 (defmacro imenu-progress-message (prevpos &optional relpos reverse)
283 ;; imenu-scanning-message
286 ;; `(imenu--relative-position ,reverse))))
290 ;; (message imenu-scanning-message pos)
302 ;; FIXME: This is the only imenu-example-* definition that's actually used,
305 (defun imenu-example--name-and-position ()
310 ;; [ydi] modified for imenu-use-markers
311 (let ((beg (if imenu-use-markers (point-marker) (point)))
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.
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 '())
343 (imenu-progress-message prev-pos 0)
346 (imenu-progress-message prev-pos nil t)
354 (push (imenu-example--name-and-position)
355 index-var-alist))
358 (push (imenu-example--name-and-position)
359 index-alist))
367 (push (imenu-example--name-and-position)
368 index-type-alist))
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))
386 (defvar imenu-example--function-name-regexp-c
395 (defun imenu-example--create-c-index (&optional regexp)
396 (let ((index-alist '())
399 (imenu-progress-message prev-pos 0)
403 (or regexp imenu-example--function-name-regexp-c)
405 (imenu-progress-message prev-pos)
412 (push (imenu-example--name-and-position) index-alist))))
413 (imenu-progress-message prev-pos 100)
414 (nreverse index-alist)))
423 ;; The item to use in the index for rescanning the buffer.
424 (defconst imenu--rescan-item '("*Rescan*" . -99))
426 ;; The latest buffer index.
428 (defvar imenu--index-alist nil
429 "The buffer index alist computed for this buffer in Imenu.
440 The function `imenu--subalist-p' tests an element and returns t
444 element recalculates the buffer's index alist.")
446 (make-variable-buffer-local 'imenu--index-alist)
448 (defvar imenu--last-menubar-index-alist nil
449 "The latest buffer index alist used to update the menu bar menu.")
451 (make-variable-buffer-local 'imenu--last-menubar-index-alist)
455 (defvar imenu--history-list nil)
465 ;;; Sorts the items depending on their index name.
468 (defun imenu--sort-by-name (item1 item2)
471 (defun imenu--sort-by-position (item1 item2)
474 (defun imenu--relative-position (&optional reverse)
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)
508 ;;; In any case, add TITLE to the front of the alist.
509 (defun imenu--split-menu (menulist title)
511 (if (memq imenu--rescan-item menulist)
512 (setq keep-at-top (cons imenu--rescan-item nil)
513 menulist (delq imenu--rescan-item menulist)))
516 (when (imenu--subalist-p item)
519 (if imenu-sort-function
520 (setq menulist (sort (copy-sequence menulist) imenu-sort-function)))
521 (if (> (length menulist) imenu-max-items)
526 (imenu--split menulist imenu-max-items))))
532 (defun imenu--split-submenus (alist)
538 (imenu--split-menu (cdr elt) (car elt))
542 ;;; Truncate all strings in MENULIST to imenu-max-item-length
543 (defun imenu--truncate-items (menulist)
548 (imenu--truncate-items (cdr item)))
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))))))
556 (defun imenu--make-index-alist (&optional noerror)
557 "Create an index alist for the definitions in the current buffer.
558 This works by using the hook function `imenu-create-index-function'.
562 See `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
569 (setq imenu--index-alist
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))
586 (defvar imenu--cleanup-seen)
588 (defun imenu--cleanup (&optional alist)
591 ;; and use imenu--index-alist.
593 (setq imenu--cleanup-seen (cons alist imenu--cleanup-seen))
594 (setq alist imenu--index-alist imenu--cleanup-seen (list alist)))
603 ((memq (cdr item) imenu--cleanup-seen))
604 ((imenu--subalist-p item)
605 (imenu--cleanup (cdr item)))))
609 (defun imenu--create-keymap (title alist &optional cmd)
615 ((imenu--subalist-p item)
616 (imenu--create-keymap (car item) (cdr item) cmd))
622 (defun imenu--in-alist (str alist)
638 (if (setq res (imenu--in-alist str tail))
640 ((if imenu-name-lookup-function
641 (funcall imenu-name-lookup-function str head)
646 (defvar imenu-syntax-alist nil
647 "Alist of syntax table modifiers to use while in `imenu--generic-function'.
654 normally have symbol syntax to simplify `imenu-expression'
657 (make-variable-buffer-local 'imenu-syntax-alist)
659 (defun imenu-default-create-index-function ()
660 "*Default function to create an index alist of the current buffer.
663 `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
664 All the results returned by the latter are gathered into an index alist.
668 `imenu--generic-function' with `imenu-generic-expression' as argument."
669 ;; These should really be done by setting imenu-create-index-function
671 (cond ((and imenu-prev-index-position-function
672 imenu-extract-index-name-function)
673 (let ((index-alist '())
676 (imenu-progress-message prev-pos 0 t)
678 (while (funcall imenu-prev-index-position-function)
679 (imenu-progress-message prev-pos nil t)
681 (setq name (funcall imenu-extract-index-name-function)))
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))
689 ((and imenu-generic-expression)
690 (imenu--generic-function imenu-generic-expression))
692 (error "This buffer cannot use `imenu-default-create-index-function'"))))
695 ;;; Generic index gathering function.
698 (defvar imenu-case-fold-search t
699 "Defines whether `imenu--generic-function' should fold case when matching.
702 for modes which use `imenu--generic-function'. If it is not set, but
705 (make-variable-buffer-local 'imenu-case-fold-search)
709 (defun imenu--generic-function (patterns)
710 "Return an index alist of the current buffer based on PATTERNS.
717 element in the index alist when it matches; the latter creates a
736 The variable `imenu-case-fold-search' determines whether or not the
737 regexp matches are case sensitive, and `imenu-syntax-alist' can be
740 See `lisp-imenu-generic-expression' for an example of PATTERNS.
742 Returns an index of the current buffer as an alist. The elements in
747 They may also be nested index alists like:
751 (let ((index-alist (list 'dummy))
753 (case-fold-search (if (or (local-variable-p 'imenu-case-fold-search)
755 imenu-case-fold-search
759 (slist imenu-syntax-alist))
769 (imenu-progress-message prev-pos 0 t)
774 ;; map over the elements of imenu-generic-expression
779 (index (nth 2 pat))
794 (goto-char (match-beginning index))
797 (imenu-progress-message prev-pos nil t)
800 (unless (assoc menu-title index-alist)
801 (push (list menu-title) index-alist))
802 (if imenu-use-markers
806 (nconc (list (match-string-no-properties index)
809 (cons (match-string-no-properties index)
813 (menu (assoc menu-title index-alist)))
822 (imenu-progress-message prev-pos 100 t)
825 (dolist (item index-alist)
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))
839 (defun imenu-find-default (guess completions)
851 (defun imenu--completion-buffer (index-alist &optional prompt)
854 Return one of the entries in index-alist or nil."
858 (prepared-index-alist
859 (if (not imenu-space-replacement) index-alist
862 (cons (subst-char-in-string ?\s (aref imenu-space-replacement 0)
865 index-alist))))
867 (setq name (or (imenu-find-default name prepared-index-alist) name)))
869 ((and name (imenu--in-alist name prepared-index-alist))
874 (if (not imenu-eager-completion-buffer)
875 (add-hook 'minibuffer-setup-hook 'minibuffer-completion-help))
877 prepared-index-alist
878 nil t nil 'imenu--history-list name)))
881 (setq choice (assoc name prepared-index-alist))
882 (if (imenu--subalist-p choice)
883 (imenu--completion-buffer (cdr choice) prompt)
886 (defun imenu--mouse-menu (index-alist event &optional title)
887 "Let the user select from a buffer index from a mouse menu.
889 INDEX-ALIST is the buffer index and EVENT is a mouse event.
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)
900 (defun imenu-choose-buffer-index (&optional prompt alist)
901 "Let the user select from a buffer index and return the chosen index.
907 If you call this function with index alist ALIST, then it lets the user
910 With no index alist ALIST, it calls `imenu--make-index-alist' to
911 create the index alist.
913 If `imenu-use-popup-menu' is nil, then the completion buffer
917 (let (index-alist
928 (setq index-alist (if alist alist (imenu--make-index-alist)))
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)))
940 (defun imenu-add-to-menubar (name)
941 "Add an `imenu' entry to the menu bar for the current buffer.
943 See the command `imenu' for more information."
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)))
952 (setq imenu--last-menubar-index-alist nil)
953 (define-key newmap [menu-bar index]
956 (add-hook 'menu-bar-update-hook 'imenu-update-menubar))
960 (defun imenu-add-menubar-index ()
963 A trivial interface to `imenu-add-to-menubar' suitable for use in a hook."
965 (imenu-add-to-menubar "Index"))
967 (defvar imenu-buffer-menubar nil)
969 (defvar imenu-menubar-modified-tick 0
971 to `imenu-update-menubar'.")
972 (make-variable-buffer-local 'imenu-menubar-modified-tick)
974 (defun imenu-update-menubar ()
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
982 (unless (equal index-alist imenu--last-menubar-index-alist)
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
988 (setq menu1 (imenu--create-keymap (car menu)
992 'imenu--menubar-select))
993 (setq old (lookup-key (current-local-map) [menu-bar index]))
996 (defun imenu--menubar-select (item)
998 (if (equal item imenu--rescan-item)
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)
1007 (imenu item)
1010 (defun imenu-default-goto-function (name position &optional rest)
1015 function placed in a special index-item."
1023 (defun imenu (index-item)
1025 INDEX-ITEM specifies the position. See `imenu-choose-buffer-index'
1027 (interactive (list (imenu-choose-buffer-index)))
1029 (if (stringp index-item)
1030 (setq index-item (assoc index-item (imenu--make-index-alist))))
1031 (when index-item
1033 (let* ((is-special-item (listp (cdr index-item)))
1036 (nth 2 index-item) imenu-default-goto-function))
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)))
1044 '("^No items suitable for an index found in this buffer$"
1045 "^This buffer cannot use `imenu-default-create-index-function'$"
1047 (add-to-list 'debug-ignored-errors mess))
1049 (provide 'imenu)
1052 ;;; imenu.el ends here