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

Эта переменная представляет собой 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

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

В alist индекса могут быть элементы трёх типов. Простые элементы имеют следующий вид:

(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, чтобы сформировать alist индекса. Однако, если одна из этих двух переменных равна nil, функция по умолчанию использует вместо этого imenu-generic-expression.

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

Если Emacs собран с поддержкой tree-sitter, он может автоматически создавать индекс Imenu, если основной режим задаёт соответствующие переменные.

Переменная: treesit-simple-imenu-settings

Эта переменная указывает Emacs, как создавать индексы Imenu. Её значением должен быть список (category regexp pred name-fn).

category должно быть именем категории, например «Функция», «Класс» и т. д. regexp должно быть регулярным выражением, соответствующим типу узлов, относящихся к category. pred должно быть либо nil, либо функцией, принимающей узел в качестве аргумента. Она должна возвращать значение, не равное nil, если узел подходит для category, и nil в противном случае.

category также может быть равно nil; в этом случае записи, соответствующие regexp и pred, не группируются по category.

name-fn должно быть либо nil, либо функцией, принимающей узел defun и возвращающей имя этого defun, например имя функции для определения функции. Если name-fn равно nil, вместо него используется treesit-defun-name (см. Разработка основных режимов с помощью tree-sitter).

treesit-major-mode-setup (см. Разработка основных режимов с помощью tree-sitter) автоматически настраивает Imenu, если эта переменная не равна nil.

Переменная: treesit-aggregated-simple-imenu-settings

Эта переменная позволяет основным режимам настраивать Imenu для нескольких языков. Её значение — alist, сопоставляющий символы языков с настройками Imenu в форме, описанной выше для значения treesit-simple-imenu-settings.

Если эта переменная не равна nil, она переопределяет treesit-simple-imenu-settings при настройке Imenu.