Завершение и минибуфер

В этом разделе описывается базовый интерфейс чтения из минибуфера с завершением.

Функция: completing-read prompt collection &optional predicate require-match initial history default inherit-input-method

Эта функция считывает строку в минибуфере, помогая пользователю с помощью завершения. Она активирует минибуфер с запросом prompt, который должен быть строкой.

Фактическое завершение выполняется путем передачи таблицы завершения collection и предиката завершения predicate функции try-completion (см. Базовое завершение). Это происходит в определенных командах, связанных в локальных картах клавиш, используемых для завершения. Некоторые из этих команд также вызывают test-completion. Таким образом, если predicate не nil, он должен быть совместим с collection и completion-ignore-case. См. Определение test-completion.

См. Программируемое завершение для подробных требований, когда collection является функцией.

Значение необязательного аргумента require-match определяет, как пользователь может выйти из минибуфера:

• Если nil, обычные команды выхода из минибуфера работают независимо от ввода в минибуфере.
• Если t, обычные команды выхода из минибуфера не выйдут, пока ввод не завершится элементом из collection.
• Если confirm, пользователь может выйти с любым вводом, но его попросят подтвердить, если ввод не является элементом из collection.
• Если confirm-after-completion, пользователь может выйти с любым вводом, но его попросят подтвердить, если предыдущая команда была командой завершения (т. е., одной из команд в minibuffer-confirm-exit-commands) и результат ввода не является элементом из collection. См. Команды завершения.
• Любое другое значение require-match ведет себя как t, за исключением того, что команды выхода не выйдут, если будет выполнено завершение.

Однако пустой ввод всегда разрешен, независимо от значения require-match; в этом случае completing-read возвращает первый элемент из default, если это список; "", если default является nil; или default. Строка или строки в default также доступны пользователю через команды истории.

Функция completing-read использует minibuffer-local-completion-map в качестве карты клавиш, если require-match равно nil, и использует minibuffer-local-must-match-map, если require-match не равно nil. См. Команды завершения.

Аргумент history указывает, какую переменную списка истории использовать для сохранения ввода и для команд истории минибуфера. По умолчанию используется minibuffer-history. Если history является символом t, история не записывается. См. История минибуфера.

Аргумент initial в основном устарел; мы рекомендуем использовать значение, отличное от nil, только в сочетании с указанием ячейки cons для history. См. Начальный ввод. Для ввода по умолчанию используйте default вместо этого.

Если аргумент inherit-input-method не равен nil, то минибуфер наследует текущий метод ввода (см. Методы ввода) и настройку enable-multibyte-characters (см. Представления текста) из того буфера, который был активен до входа в минибуфер.

Если переменная completion-ignore-case не равна nil, завершение игнорирует регистр при сравнении ввода с возможными совпадениями. См. Базовое завершение. В этом режиме работы predicate также должен игнорировать регистр, иначе вы получите неожиданные результаты.

Вот пример использования completing-read:

(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Complete a foo: fo∗
---------- Buffer: Minibuffer ----------

Если пользователь затем набирает DEL DEL b RET, completing-read возвращает barfoo.

Функция completing-read связывает переменные, чтобы передавать информацию командам, которые фактически выполняют завершение. Они описаны в следующем разделе.

Переменная: completing-read-function

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