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 positions of the definitions or portions of in the buffer, so the user can pick one of them to move to. This section explains how to customize Imenu for a major mode.

The usual and simplest way is to set the variable imenu-generic-expression:

Variable: imenu-generic-expression

This variable, if non-nil, specifies regular expressions for finding definitions for Imenu. In the simplest case, elements should look like this:

(menu-title regexp subexp)

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.

The second item in the list, regexp, is a regular expression (see section Regular Expressions); wherever it matches, that is a definition to mention in the buffer index. The third item, subexp, 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 a special index item which, if selected by the user, calls function with arguments item-name, the buffer position, and arguments.

For Emacs Lisp mode, pattern 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 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 (see section 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 patterns can then use `\\sw+' instead of `\\(\\sw\\|\\s_\\)+'. Note that this technique may be inconvenient to use 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 for finding the next definition to mention in the buffer index, moving backwards in the file.

The function should leave point at the place to be connected to the index item; it should return nil if it doesn't find another item.

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 variables 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 for the current buffer. It is called within save-excursion, so where it leaves point makes no difference.

The default value is a function that uses imenu-generic-expression to produce the index alist. If you specify a different function, then imenu-generic-expression is not used.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-index-alist

This variable holds the index alist for the current buffer. Setting it makes it buffer-local in the current buffer.

Simple elements in the alist look like (index-name . index-position). Selecting a simple element has the effect of moving to position index-position in the buffer.

Special elements look like (index-name position function arguments...). Selecting a special element performs

(funcall function index-name position arguments...)

A nested sub-alist element looks like (index-name sub-alist).

Go to the first, previous, next, last section, table of contents.