path: root/devdocs/elisp/imenu.html

 <h3 class="section">Imenu</h3>  <p><em>Imenu</em> 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 <code>imenu-add-to-menubar</code>. </p> <dl> <dt id="imenu-add-to-menubar">Command: <strong>imenu-add-to-menubar</strong> <em>name</em>
</dt> <dd><p>This function defines a local menu bar item named <var>name</var> to run Imenu. </p></dd>
</dl> <p>The user-level commands for using Imenu are described in the Emacs Manual (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html#Imenu">Imenu</a> in <cite>the Emacs Manual</cite>). This section explains how to customize Imenu’s method of finding definitions or buffer portions for a particular major mode. </p> <p>The usual and simplest way is to set the variable <code>imenu-generic-expression</code>: </p> <dl> <dt id="imenu-generic-expression">Variable: <strong>imenu-generic-expression</strong>
</dt> <dd>
<p>This variable, if non-<code>nil</code>, is a list that specifies regular expressions for finding definitions for Imenu. Simple elements of <code>imenu-generic-expression</code> look like this: </p> <div class="example"> <pre class="example">(<var>menu-title</var> <var>regexp</var> <var>index</var>)
</pre>
</div> <p>Here, if <var>menu-title</var> is non-<code>nil</code>, it says that the matches for this element should go in a submenu of the buffer index; <var>menu-title</var> itself specifies the name for the submenu. If <var>menu-title</var> is <code>nil</code>, the matches for this element go directly in the top level of the buffer index. </p> <p>The second item in the list, <var>regexp</var>, is a regular expression (see <a href="regular-expressions">Regular Expressions</a>); anything in the buffer that it matches is considered a definition, something to mention in the buffer index. The third item, <var>index</var>, is a non-negative integer that indicates which subexpression in <var>regexp</var> matches the definition’s name. </p> <p>An element can also look like this: </p> <div class="example"> <pre class="example">(<var>menu-title</var> <var>regexp</var> <var>index</var> <var>function</var> <var>arguments</var>…)
</pre>
</div> <p>Each match for this element creates an index item, and when the index item is selected by the user, it calls <var>function</var> with arguments consisting of the item name, the buffer position, and <var>arguments</var>. </p> <p>For Emacs Lisp mode, <code>imenu-generic-expression</code> could look like this: </p> <div class="example"> <pre class="example">((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
</pre>
<pre class="example"> ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
</pre>
<pre class="example"> ("*Types*"
  "^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
</pre>
</div> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl> <dl> <dt id="imenu-case-fold-search">Variable: <strong>imenu-case-fold-search</strong>
</dt> <dd>
<p>This variable controls whether matching against the regular expressions in the value of <code>imenu-generic-expression</code> is case-sensitive: <code>t</code>, the default, means matching should ignore case. </p> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl> <dl> <dt id="imenu-syntax-alist">Variable: <strong>imenu-syntax-alist</strong>
</dt> <dd>
<p>This variable is an alist of syntax table modifiers to use while processing <code>imenu-generic-expression</code>, to override the syntax table of the current buffer. Each element should have this form: </p> <div class="example"> <pre class="example">(<var>characters</var> . <var>syntax-description</var>)
</pre>
</div> <p>The <small>CAR</small>, <var>characters</var>, can be either a character or a string. The element says to give that character or characters the syntax specified by <var>syntax-description</var>, which is passed to <code>modify-syntax-entry</code> (see <a href="syntax-table-functions">Syntax Table Functions</a>). </p> <p>This feature is typically used to give word syntax to characters which normally have symbol syntax, and thus to simplify <code>imenu-generic-expression</code> and speed up matching. For example, Fortran mode uses it this way: </p> <div class="example"> <pre class="example">(setq imenu-syntax-alist '(("_$" . "w")))
</pre>
</div> <p>The <code>imenu-generic-expression</code> regular expressions can then use ‘<samp>\\sw+</samp>’ instead of ‘<samp>\\(\\sw\\|\\s_\\)+</samp>’. 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. </p> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl> <p>Another way to customize Imenu for a major mode is to set the variables <code>imenu-prev-index-position-function</code> and <code>imenu-extract-index-name-function</code>: </p> <dl> <dt id="imenu-prev-index-position-function">Variable: <strong>imenu-prev-index-position-function</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, 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 <code>nil</code> 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-<code>nil</code> value. </p> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl> <dl> <dt id="imenu-extract-index-name-function">Variable: <strong>imenu-extract-index-name-function</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, its value should be a function to return the name for a definition, assuming point is in that definition as the <code>imenu-prev-index-position-function</code> function would leave it. </p> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl> <p>The last way to customize Imenu for a major mode is to set the variable <code>imenu-create-index-function</code>: </p> <dl> <dt id="imenu-create-index-function">Variable: <strong>imenu-create-index-function</strong>
</dt> <dd>
<p>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 <code>save-excursion</code>, so where it leaves point makes no difference. </p> <p>The index alist can have three types of elements. Simple elements look like this: </p> <div class="example"> <pre class="example">(<var>index-name</var> . <var>index-position</var>)
</pre>
</div> <p>Selecting a simple element has the effect of moving to position <var>index-position</var> in the buffer. Special elements look like this: </p> <div class="example"> <pre class="example">(<var>index-name</var> <var>index-position</var> <var>function</var> <var>arguments</var>…)
</pre>
</div> <p>Selecting a special element performs: </p> <div class="example"> <pre class="example">(funcall <var>function</var>
         <var>index-name</var> <var>index-position</var> <var>arguments</var>…)
</pre>
</div> <p>A nested sub-alist element looks like this: </p> <div class="example"> <pre class="example">(<var>menu-title</var> . <var>sub-alist</var>)
</pre>
</div> <p>It creates the submenu <var>menu-title</var> specified by <var>sub-alist</var>. </p> <p>The default value of <code>imenu-create-index-function</code> is <code>imenu-default-create-index-function</code>. This function calls the value of <code>imenu-prev-index-position-function</code> and the value of <code>imenu-extract-index-name-function</code> to produce the index alist. However, if either of these two variables is <code>nil</code>, the default function uses <code>imenu-generic-expression</code> instead. </p> <p>Setting this variable makes it buffer-local in the current buffer. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Imenu.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Imenu.html</a>
  </p>
</div>