Imenu

Imenu — это функция, которая позволяет пользователям выбрать определение или раздел в буфере из меню, которое перечисляет все определения, чтобы перейти непосредственно к этому месту в буфере. Imenu работает, создавая индекс буфера, который перечисляет имена и позиции буфера определений или других именованных частей буфера; затем пользователь может выбрать один из них и переместить точку к нему. Основные режимы могут добавлять элемент в строку меню для использования Imenu, используя imenu-add-to-menubar.

Команда: imenu-add-to-menubar name

Эта функция определяет локальный элемент строки меню с именем name для запуска Imenu.

Команды уровня пользователя для использования Imenu описаны в Руководстве Emacs (см. Imenu в Руководстве Emacs). В этом разделе объясняется, как настроить метод поиска Imenu определений или частей буфера для конкретного основного режима.

Обычный и самый простой способ — установить переменную imenu-generic-expression:

Переменная: imenu-generic-expression

Эта переменная, если не nil, представляет собой список, который определяет регулярные выражения для поиска определений для Imenu. Простые элементы imenu-generic-expression выглядят так:

(menu-title regexp index)

Здесь, если menu-title не nil, это означает, что совпадения для этого элемента должны быть помещены в подменю индекса буфера; сама menu-title указывает имя подменю. Если menu-title nil, совпадения для этого элемента попадают непосредственно в верхний уровень индекса буфера.

Второй элемент в списке, regexp, — это регулярное выражение (см. Регулярные выражения); все в буфере, которое оно соответствует, считается определением, что следует упомянуть в индексе буфера. Третий элемент, index, — это целое число без знака, которое указывает, какая подстрока в regexp соответствует имени определения.

Элемент также может выглядеть так:

(menu-title regexp index function arguments…)

Каждый совпадение для этого элемента создает элемент индекса, и когда пользователь выбирает элемент индекса, он вызывает function с аргументами, состоящими из имени элемента, позиции буфера и arguments.

Для режима Emacs Lisp imenu-generic-expression может выглядеть так:

((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))

Установка этой переменной делает ее локальной для буфера в текущем буфере.

Переменная: imenu-case-fold-search

Эта переменная управляет тем, чувствителен ли поиск совпадений по регулярным выражениям в значении imenu-generic-expression к регистру: t, значение по умолчанию, означает, что поиск совпадений должен игнорировать регистр.

Установка этой переменной делает ее локальной для буфера в текущем буфере.

Переменная: imenu-syntax-alist

Эта переменная представляет собой список атрибутов синтаксической таблицы для использования во время обработки imenu-generic-expression, чтобы переопределить синтаксическую таблицу текущего буфера. Каждый элемент должен иметь такой вид:

(characters . syntax-description)

CAR, characters, может быть символом или строкой. Элемент указывает, что этому символу или символам должен быть предоставлен синтаксис, указанный в syntax-description, который передается в modify-syntax-entry (см. Функции синтаксической таблицы).

Эта функция обычно используется для присвоения синтаксиса слов символам, которые обычно имеют синтаксис символов, и, следовательно, для упрощения imenu-generic-expression и ускорения поиска совпадений. Например, режим Fortran использует его таким образом:

(setq imenu-syntax-alist '(("_$" . "w")))

Регулярные выражения imenu-generic-expression могут использовать «\\sw+» вместо «\\(\\sw\\|\\s_\\)+». Обратите внимание, что эта техника может быть неудобной, когда режиму требуется ограничить начальный символ имени меньшим набором символов, чем разрешен в остальной части имени.

Установка этой переменной делает ее локальной для буфера в текущем буфере.

Другой способ настройки Imenu для основного режима — установить переменные imenu-prev-index-position-function и imenu-extract-index-name-function:

Переменная: imenu-prev-index-position-function

Если эта переменная не nil, ее значение должно быть функцией, которая находит следующее определение для помещения в индекс буфера, сканируя буфер назад от точки. Она должна возвращать nil если не находит другое определение перед точкой. В противном случае она должна оставлять точку в месте, где находит определение, и возвращать любое не-nil значение.

Установка этой переменной делает ее локальной для буфера в текущем буфере.

Переменная: imenu-extract-index-name-function

Если эта переменная не nil, ее значение должно быть функцией для возврата имени определения, предполагая, что точка находится в этом определении, как функция imenu-prev-index-position-function оставила бы ее.

Установка этой переменной делает ее локальной для буфера в текущем буфере.

Последний способ настройки Imenu для основного режима — установить переменную imenu-create-index-function:

Переменная: imenu-create-index-function

Эта переменная задает функцию для создания индекса буфера. Функция не принимает аргументов и возвращает список индексов для текущего буфера. Она вызывается внутри save-excursion, поэтому то, где она оставляет точку, не имеет значения.

Список индексов может иметь три типа элементов. Простые элементы выглядят так:

(index-name . index-position)

Выбор простого элемента приводит к перемещению в позицию index-position в буфере. Специальные элементы выглядят так:

(index-name index-position function arguments…)

Выбор специального элемента выполняет:

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

Вложенный подсписок элементов выглядит так:

(menu-title . sub-alist)

Он создает подменю menu-title, заданное sub-alist.

Значение по умолчанию для imenu-create-index-function — imenu-default-create-index-function. Эта функция вызывает значение imenu-prev-index-position-function и значение imenu-extract-index-name-function для создания списка индексов. Однако, если одна из этих двух переменных nil, функция по умолчанию использует imenu-generic-expression вместо этого.

Установка этой переменной делает ее локальной для буфера в текущем буфере.