Programmed Completion — Elisp

Программируемое завершение

Иногда невозможно или неудобно заранее создать alist или obarray, содержащий все предполагаемые варианты завершения. В таком случае можно передать собственную функцию для вычисления завершения заданной строки. Это называется программируемым завершением. Emacs использует программируемое завершение при завершении имен файлов (см. Завершение имен файлов), а также во многих других случаях.

Чтобы воспользоваться этой возможностью, передайте функцию в качестве аргумента collection функции completing-read. Функция completing-read передает вашу функцию завершения функциям try-completion, all-completions и другим базовым функциям завершения, которые затем поручают всю работу вашей функции.

Функция завершения должна принимать три аргумента:

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

nil

Этот флаг задает операцию try-completion. Если совпадений нет, функция должна вернуть nil; если указанная строка является единственным точным совпадением — t; в остальных случаях она должна вернуть самую длинную общую подстроку-префикс всех совпадений.

t

Этот флаг задает операцию all-completions. Функция должна вернуть список всех возможных вариантов завершения указанной строки.

lambda

Этот флаг задает операцию test-completion. Если указанная строка точно совпадает с одним из вариантов завершения, функция должна вернуть t; в противном случае — nil.

(boundaries . suffix)

Этот флаг задает операцию completion-boundaries. Функция должна вернуть (boundaries start . end), где start — позиция начальной границы в указанной строке, а end — позиция конечной границы в suffix.

Если программа на Lisp возвращает нетривиальные границы, она должна обеспечить согласованность операции all-completions с этими границами. Варианты завершения, возвращаемые функцией all-completions, должны относиться только к той части префикса и суффикса, которая охватывается границами завершения. Точное описание ожидаемой семантики границ завершения см. в разделе Базовые функции завершения.

metadata

Этот флаг запрашивает информацию о состоянии текущего завершения. Возвращаемое значение должно иметь вид (metadata . alist), где alist — alist, элементы которого описаны ниже.

Если флаг имеет любое другое значение, функция завершения должна вернуть nil.

Ниже приведен список записей метаданных, которые функция завершения может возвращать в ответ на аргумент-флаг metadata:

category: Значением должен быть символ, описывающий тип текста, который функция завершения пытается завершить. Если символ совпадает с одним из ключей в completion-category-overrides, стандартное поведение завершения переопределяется. См. раздел Переменные завершения.
annotation-function: Значением должна быть функция для добавления аннотаций к вариантам завершения. Функция должна принимать один аргумент — string, представляющий возможный вариант завершения. Она должна возвращать строку, которая отображается после строки варианта завершения string в буфере *Completions*. Если эта функция не задает собственный face для строки суффикса аннотации, к этой строке по умолчанию применяется face completions-annotations.
affixation-function: Значением должна быть функция для добавления префиксов и суффиксов к вариантам завершения. Функция должна принимать один аргумент — completions, то есть список возможных вариантов завершения. Она должна возвращать список completions, каждый элемент которого содержит список из трех элементов: вариант завершения, префикс, отображаемый перед строкой варианта завершения в буфере *Completions*, и суффикс, отображаемый после строки варианта завершения. Эта функция имеет приоритет над annotation-function.
group-function: Значением должна быть функция для группировки кандидатов завершения. Функция должна принимать два аргумента: completion — кандидат завершения, и transform — булев флаг. Если transform имеет значение nil, функция должна вернуть заголовок группы, к которой относится кандидат. Возвращенный заголовок также может быть равен nil. В противном случае функция должна вернуть преобразованный кандидат. Например, преобразование может удалять избыточный префикс, отображаемый в заголовке группы.
display-sort-function: Значением должна быть функция для сортировки вариантов завершения. Функция должна принимать один аргумент — список строк вариантов завершения — и возвращать отсортированный список строк вариантов завершения. Допускается деструктивное изменение входного списка.
cycle-sort-function: Значением должна быть функция для сортировки вариантов завершения, когда completion-cycle-threshold не равен nil и пользователь переключается между вариантами завершения. См. раздел Настройки завершения в Руководстве по GNU Emacs. Список аргументов и возвращаемое значение такие же, как у display-sort-function.

Функция: completion-table-dynamic function &optional switch-buffer

Эта функция позволяет удобно написать функцию, которая может работать как функция программируемого завершения. Аргумент function должен быть функцией, принимающей один аргумент — строку — и возвращающей таблицу завершения (см. Базовые функции завершения), содержащую все возможные варианты завершения. Возвращенная функцией function таблица может также содержать элементы, не совпадающие со строковым аргументом; функция completion-table-dynamic автоматически отфильтрует их. В частности, функция function может игнорировать свой аргумент и возвращать полный список всех возможных вариантов завершения. Функцию completion-table-dynamic можно рассматривать как преобразователь между функцией function и интерфейсом для функций программируемого завершения.

Если необязательный аргумент switch-buffer не равен nil и завершение выполняется в минибуфере, функция function будет вызвана так, чтобы текущим буфером был буфер, из которого был вызван минибуфер.

Возвращаемое значение функции completion-table-dynamic — это функция, которую можно использовать в качестве 2-го аргумента функций try-completion и all-completions. Обратите внимание, что эта функция всегда будет возвращать пустые метаданные и тривиальные границы.

Функция: completion-table-with-cache function &optional ignore-case: Это обертка для completion-table-dynamic, которая сохраняет последнюю пару аргумент—результат. Благодаря этому для нескольких поисков с одним и тем же аргументом функцию function достаточно вызвать только один раз. Это может быть полезно при выполнении медленной операции, например при вызове внешнего процесса.

Функция: completion-table-with-metadata table metadata: Эта функция создает таблицу завершения, которая работает так же, как существующая таблица завершения table, за исключением того, что новая таблица использует alist metadata в качестве метаданных завершения.