Programmed Completion — Elisp

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

Иногда невозможно или неудобно создать список или массив, содержащий все предполагаемые возможные завершения заранее. В таком случае вы можете предоставить собственную функцию для вычисления завершения заданной строки. Это называется программируемым завершением. 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 — список, элементы которого описаны ниже.

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

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

category: Значение должно быть символом, описывающим вид текста, который функция завершения пытается завершить. Если символ совпадает с одним из ключей в completion-category-overrides, обычное поведение завершения переопределяется. См. Переменные завершения.
annotation-function: Значение должно быть функцией для комментирования завершений. Функция должна принимать один аргумент, string, который является возможным завершением. Она должна возвращать строку, которая отображается после завершения string в буфере *Completions*. Если эта функция не устанавливает собственный стиль для строки суффикса аннотации, стиль 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 только один раз. Это может быть полезно, когда вовлечена медленная операция, например, вызов внешнего процесса.