Дополнение и минибуфер

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

Функция: 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. См. Команды минибуфера, выполняющие дополнение.
• Если это функция, она вызывается с введёнными данными в качестве единственного аргумента. Функция должна возвращать значение, отличное от nil, если введённые данные допустимы.
• Любое другое значение require-match ведёт себя как t, за исключением того, что команды выхода не приведут к выходу, если выполнят дополнение.

Однако пустой ввод всегда допустим независимо от значения require-match; в этом случае completing-read возвращает первый элемент default, если это список; "", если default — nil; или default. Строка или строки из default также доступны пользователю с помощью команд истории (см. Команды минибуфера). Кроме того, кандидаты для дополнения добавляются в «будущую историю», когда значения в default исчерпываются с помощью M-n; см. minibuffer-default-add-function.

Функция 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.

Если нужно запросить у пользователя несколько строк, например несколько элементов списка или несколько параметров (например, пользователя, хост и порт) подключения, можно использовать completing-read-multiple. Она позволяет вводить несколько строк, разделённых строкой-разделителем (по умолчанию — табуляциями и запятыми; настройте crm-separator, чтобы изменить это), и предоставляет дополнение для каждой вводимой пользователем строки. Функция возвращает прочитанные строки в виде списка.