Переменные дополнения

Вот некоторые переменные, которые можно использовать для изменения поведения дополнения по умолчанию.

Пользовательский параметр: completion-styles

Значение этой переменной — список стилей дополнения (символов), используемых для выполнения дополнения. Стиль дополнения — это набор правил для создания вариантов дополнения. Для каждого символа в этом списке должна быть соответствующая запись в completion-styles-alist.

Переменная: completion-styles-alist

Эта переменная содержит список доступных стилей дополнения. Каждый элемент списка имеет вид

(style try-completion all-completions doc)

Здесь style — имя стиля дополнения (символ), которое можно использовать в переменной completion-styles для ссылки на этот стиль; try-completion — функция, выполняющая дополнение; all-completions — функция, перечисляющая варианты дополнения; а doc — строка с описанием стиля дополнения.

Функции try-completion и all-completions должны принимать по четыре аргумента: string, collection, predicate и point. Аргументы string, collection и predicate имеют то же значение, что и в try-completion (см. раздел Базовые функции дополнения), а аргумент point задаёт позицию точки внутри string. Каждая функция должна возвращать значение, отличное от nil, если она выполнила свою задачу, и nil, если не выполнила (например, если невозможно дополнить string в соответствии со стилем дополнения).

Когда пользователь вызывает такую команду дополнения, как minibuffer-complete (см. раздел Команды минибуфера, выполняющие дополнение), Emacs ищет первый стиль в списке completion-styles и вызывает его функцию try-completion. Если эта функция возвращает nil, Emacs переходит к следующему указанному стилю дополнения и вызывает его функцию try-completion, и так далее, пока одна из функций try-completion успешно не выполнит дополнение и не вернёт значение, отличное от nil. Аналогичная процедура используется для перечисления вариантов дополнения с помощью функций all-completions.

Описание доступных стилей дополнения см. в разделе Стили дополнения в Руководстве GNU Emacs.

Пользовательский параметр: completion-category-overrides

Эта переменная задаёт специальные стили дополнения и другое поведение при дополнении для определённых типов текста. Её значение должно быть ассоциативным списком с элементами вида (category . alist). category — символ, описывающий то, что дополняется; в настоящее время определены категории buffer, file и unicode-name, но другие категории можно определить с помощью специализированных функций дополнения (см. раздел Программируемое дополнение). alist — ассоциативный список, описывающий поведение дополнения для соответствующей категории. Поддерживаются следующие ключи ассоциативного списка:

styles

Значением должен быть список стилей дополнения (символов).

cycle

Значением должно быть значение для completion-cycle-threshold (см. раздел Параметры дополнения в Руководстве GNU Emacs), применяемое к этой категории.

cycle-sort-function

Функция сортировки элементов при циклическом переборе.

display-sort-function

Функция сортировки элементов в буфере *Completions*. Возможные значения: nil — использовать функцию сортировки из метаданных или, если это nil, использовать completions-sort; identity — не выполнять сортировку, сохраняя исходный порядок; либо любое другое значение из числа используемых в completions-sort (см. раздел Параметры дополнения в Руководстве GNU Emacs).

group-function

Функция группировки вариантов дополнения.

annotation-function

Функция добавления пояснений к вариантам дополнения.

affixation-function

Функция добавления префиксов и суффиксов к вариантам дополнения.

Полный список записей метаданных см. в разделе Программируемое дополнение.

Переменная: completion-extra-properties

Эта переменная задаёт дополнительные свойства текущей команды дополнения. Предполагается, что специализированные команды дополнения будут связывать её значение с помощью let. Её значение должно быть списком пар «свойство — значение». Поддерживаются следующие свойства:

:category

Значением должен быть символ, описывающий тип текста, который функция дополнения пытается дополнить. Если символ совпадает с одним из ключей, описанных выше для completion-category-overrides, стандартное поведение дополнения переопределяется.

:annotation-function

Значением должна быть функция добавления пояснений в буфер вариантов дополнения. Эта функция должна принимать один аргумент — вариант дополнения — и возвращать либо nil, либо строку, отображаемую рядом с вариантом дополнения. Если функция не задаёт собственное начертание для строки суффикса пояснения, к этой строке по умолчанию применяется начертание completions-annotations.

:affixation-function

Значением должна быть функция добавления префиксов и суффиксов к вариантам дополнения. Эта функция должна принимать один аргумент — список вариантов дополнения — и возвращать список вариантов дополнения с пояснениями. Каждый элемент возвращаемого списка должен быть списком из трёх элементов: вариант дополнения, строка префикса и строка суффикса. Эта функция имеет приоритет над :annotation-function.

:group-function

Функция группировки вариантов дополнения.

:display-sort-function

Функция сортировки элементов в буфере *Completions*.

:cycle-sort-function

Функция сортировки элементов при циклическом переборе.

:exit-function

Значением должна быть функция, запускаемая после выполнения дополнения. Функция должна принимать два аргумента: string и status, где string — текст, которым было дополнено поле, а status указывает, какой вид операции был выполнен: finished, если текст теперь дополнен; sole, если текст больше нельзя дополнить, но дополнение не завершено; или exact, если текст является допустимым вариантом дополнения, но его можно дополнить дальше.