elisp: Imenu
22.5 Imenu
==========
“Imenu” is a feature that lets users select a definition or section in
the buffer, from a menu which lists all of them, to go directly to that
location in the buffer. Imenu works by constructing a buffer index
which lists the names and buffer positions of the definitions, or other
named portions of the buffer; then the user can choose one of them and
move point to it. Major modes can add a menu bar item to use Imenu
using ‘imenu-add-to-menubar’.
-- Command: imenu-add-to-menubar name
This function defines a local menu bar item named NAME to run
Imenu.
The user-level commands for using Imenu are described in the Emacs
Manual (
Imenu (emacs)Imenu.). This section explains how to
customize Imenu’s method of finding definitions or buffer portions for a
particular major mode.
The usual and simplest way is to set the variable
‘imenu-generic-expression’:
-- Variable: imenu-generic-expression
This variable, if non-‘nil’, is a list that specifies regular
expressions for finding definitions for Imenu. Simple elements of
‘imenu-generic-expression’ look like this:
(MENU-TITLE REGEXP INDEX)
Here, if MENU-TITLE is non-‘nil’, it says that the matches for this
element should go in a submenu of the buffer index; MENU-TITLE
itself specifies the name for the submenu. If MENU-TITLE is ‘nil’,
the matches for this element go directly in the top level of the
buffer index.
Regular Expressions::); anything in the buffer that it matches is
considered a definition, something to mention in the buffer index.
The third item, INDEX, is a non-negative integer that indicates
which subexpression in REGEXP matches the definition’s name.
An element can also look like this:
(MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)
Each match for this element creates an index item, and when the
index item is selected by the user, it calls FUNCTION with
arguments consisting of the item name, the buffer position, and
ARGUMENTS.
For Emacs Lisp mode, ‘imenu-generic-expression’ could look like
this:
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
("*Types*"
"^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
Setting this variable makes it buffer-local in the current buffer.
-- Variable: imenu-case-fold-search
This variable controls whether matching against the regular
expressions in the value of ‘imenu-generic-expression’ is
case-sensitive: ‘t’, the default, means matching should ignore
case.
Setting this variable makes it buffer-local in the current buffer.
-- Variable: imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while
processing ‘imenu-generic-expression’, to override the syntax table
of the current buffer. Each element should have this form:
(CHARACTERS . SYNTAX-DESCRIPTION)
The CAR, CHARACTERS, can be either a character or a string. The
element says to give that character or characters the syntax
specified by SYNTAX-DESCRIPTION, which is passed to
‘modify-syntax-entry’ (Syntax Table Functions).
This feature is typically used to give word syntax to characters
which normally have symbol syntax, and thus to simplify
‘imenu-generic-expression’ and speed up matching. For example,
Fortran mode uses it this way:
(setq imenu-syntax-alist '(("_$" . "w")))
The ‘imenu-generic-expression’ regular expressions can then use
‘\\sw+’ instead of ‘\\(\\sw\\|\\s_\\)+’. Note that this technique
may be inconvenient when the mode needs to limit the initial
character of a name to a smaller set of characters than are allowed
in the rest of a name.
Setting this variable makes it buffer-local in the current buffer.
Another way to customize Imenu for a major mode is to set the
variables ‘imenu-prev-index-position-function’ and
‘imenu-extract-index-name-function’:
-- Variable: imenu-prev-index-position-function
If this variable is non-‘nil’, its value should be a function that
finds the next definition to put in the buffer index, scanning
backward in the buffer from point. It should return ‘nil’ if it
doesn’t find another definition before point. Otherwise it should
leave point at the place it finds a definition and return any
non-‘nil’ value.
Setting this variable makes it buffer-local in the current buffer.
-- Variable: imenu-extract-index-name-function
If this variable is non-‘nil’, its value should be a function to
return the name for a definition, assuming point is in that
definition as the ‘imenu-prev-index-position-function’ function
would leave it.
Setting this variable makes it buffer-local in the current buffer.
The last way to customize Imenu for a major mode is to set the
variable ‘imenu-create-index-function’:
-- Variable: imenu-create-index-function
This variable specifies the function to use for creating a buffer
index. The function should take no arguments, and return an index
alist for the current buffer. It is called within
‘save-excursion’, so where it leaves point makes no difference.
The index alist can have three types of elements. Simple elements
look like this:
(INDEX-NAME . INDEX-POSITION)
Selecting a simple element has the effect of moving to position
INDEX-POSITION in the buffer. Special elements look like this:
(INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)
Selecting a special element performs:
(funcall FUNCTION
INDEX-NAME INDEX-POSITION ARGUMENTS...)
A nested sub-alist element looks like this:
(MENU-TITLE . SUB-ALIST)
It creates the submenu MENU-TITLE specified by SUB-ALIST.
The default value of ‘imenu-create-index-function’ is
‘imenu-default-create-index-function’. This function calls the
value of ‘imenu-prev-index-position-function’ and the value of
‘imenu-extract-index-name-function’ to produce the index alist.
However, if either of these two variables is ‘nil’, the default
function uses ‘imenu-generic-expression’ instead.
Setting this variable makes it buffer-local in the current buffer.
Info Catalog
elisp: Mode Line Format
elisp: Modes
elisp: Font Lock Mode