GNU Info

(elisp)Imenu

---

Next: Font Lock Mode Prev: Mode Line Format Up: Modes

---

Enter node , (file) or (file)node

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.  This section explains how to customize how
Imenu finds the 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', 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
     (Note: Regular Expressions); anything in the buffer that it
     matches is considered a definition, something 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 consisting of
     the 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' (Note: 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 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
     shuould 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
     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)'.