Завершение в обычных буферах

Хотя завершение обычно выполняется в минибуфере, механизм завершения также может использоваться для текста в обычных буферах Emacs. Во многих основных режимах завершение в буфере выполняется командой C-M-i или M-TAB, привязанной к completion-at-point. См. Завершение символов в Справочнике GNU Emacs. Эта команда использует переменную специального крючка completion-at-point-functions.

Переменная: completion-at-point-functions

Значение этого специального крючка должно быть списком функций, которые используются для вычисления таблицы завершения (см. Основное завершение) для завершения текста в позиции. Он может использоваться основными режимами для предоставления таблиц завершения, специфичных для режима (см. Основные соглашения о режимах).

Когда команда completion-at-point выполняется, она вызывает функции в списке по одной, без каких-либо аргументов. Каждая функция должна возвращать nil, если она не может и не хочет взять на себя ответственность за данные завершения для текста в позиции. В противном случае она должна вернуть список следующего формата:

(start end collection . props)

start и end определяют текст для завершения (который должен заключать позицию). collection — это таблица завершения для завершения этого текста в форме, подходящей для передачи как второго аргумента функции try-completion (см. Основное завершение); альтернативы завершения будут сгенерированы из этой таблицы завершения обычным способом с помощью стилей завершения, определенных в completion-styles (см. Переменные завершения). props — это список свойств для дополнительной информации; распознаются любые свойства из completion-extra-properties (см. Переменные завершения), а также следующие дополнительные:

:predicate

Значение должно быть предикатом, которому должны удовлетворять кандидаты на завершение.

:exclusive

Если значение равно no, то если таблица завершения не совпадает с текстом в позиции, completion-at-point переходит к следующей функции в completion-at-point-functions вместо сообщения об ошибке завершения.

Функции в этом крючке должны обычно возвращаться быстро, так как они могут вызываться очень часто (например, из post-command-hook). Настоятельно рекомендуется предоставить функцию для collection, если создание списка завершений — дорогостоящая операция. Emacs может внутренне вызывать функции в completion-at-point-functions много раз, но заботится о значении collection только для некоторых из этих вызовов. Предоставляя функцию для collection, Emacs может отложить генерацию завершений до необходимости. Можно использовать completion-table-dynamic для создания функции-обёртки:

;; Avoid this pattern.
(let ((beg ...) (end ...) (my-completions (my-make-completions)))
  (list beg end my-completions))

;; Use this instead.
(let ((beg ...) (end ...))
  (list beg
        end
        (completion-table-dynamic
          (lambda (_)
            (my-make-completions)))))

Кроме того, collection обычно не должен быть предварительно отфильтрован на основе текущего текста между start и end, так как это обязанность вызывающего функцию completion-at-point-functions для этого в соответствии со стилями завершения, которые он решает использовать.

Функция в completion-at-point-functions также может вернуть функцию вместо списка, как описано выше. В этом случае возвращённая функция вызывается без аргументов, и она полностью отвечает за выполнение завершения. Мы не рекомендуем такое использование; оно предназначено только для помощи в преобразовании старого кода на использование completion-at-point.

Первая функция в completion-at-point-functions возвращающая не-nil значение, используется completion-at-point. Остальные функции не вызываются. Исключение из этого правила — когда есть спецификация :exclusive, как описано выше.

Следующая функция предоставляет удобный способ выполнения завершения на произвольном фрагменте текста в буфере Emacs:

Функция: completion-in-region start end collection &optional predicate

Эта функция завершает текст в текущем буфере между позициями start и end, используя collection. Аргумент collection имеет то же значение, что и в try-completion (см. Основное завершение).

Эта функция вставляет текст завершения непосредственно в текущий буфер. В отличие от completing-read (см. Завершение в минибуфере), она не активирует минибуфер.

Для работы этой функции позиция должна быть где-то между start и end.