Функции завершения высокого уровня

В этом разделе описываются функции высокого уровня для чтения определенных типов имен с завершением.

В большинстве случаев вам не следует вызывать эти функции внутри лисповой функции. По возможности, весь ввод минибуфера должен осуществляться в рамках чтения аргументов команды, в соответствии со спецификацией interactive. См. Определение команд.

Функция: read-buffer prompt &optional default require-match predicate

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

Аргумент prompt должен быть строкой, заканчивающейся двоеточием и пробелом. Если default не nil, функция вставляет его в prompt перед двоеточием, следуя соглашению для чтения из минибуфера со значением по умолчанию (см. Рекомендации по программированию).

Необязательный аргумент require-match имеет то же значение, что и в completing-read. См. Завершение минибуфера.

Необязательный аргумент predicate, если он не nil, задает функцию фильтрации буферов, которые следует учитывать: функция будет вызываться с каждым потенциальным кандидатом в качестве аргумента и должна возвращать nil, чтобы отклонить кандидата, и не-nil, чтобы принять его.

В следующем примере пользователь вводит ‘minibuffer.t’, а затем нажимает RET. Аргумент require-match — t, и единственное имя буфера, начинающееся с данного ввода, это ‘minibuffer.texi’, поэтому это имя и является значением.

(read-buffer "Buffer name: " "foo" t)

;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Buffer name (default foo): ∗
---------- Buffer: Minibuffer ----------

;; The user types minibuffer.t RET.
     ⇒ "minibuffer.texi"

Пользовательская опция: read-buffer-function

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

Пользовательская опция: read-buffer-completion-ignore-case

Если эта переменная не nil, read-buffer игнорирует регистр при выполнении завершения при чтении имени буфера.

Функция: read-command prompt &optional default

Эта функция считывает имя команды и возвращает её как лисповый символ. Аргумент prompt используется, как и в read-from-minibuffer. Помните, что команда — это всё, для чего commandp возвращает t, а имя команды — это символ, для которого commandp возвращает t. См. Интерактивный вызов.

Аргумент default указывает, что возвращать, если пользователь вводит пустой ввод. Он может быть символом, строкой или списком строк. Если это строка, read-command интернирует её перед возвращением. Если это список, read-command интернирует первый элемент этого списка. Если default — nil, это означает, что значение по умолчанию не задано; тогда, если пользователь введёт пустой ввод, возвращаемое значение — (intern ""), то есть символ с именем пустой строки и с напечатанным представлением ## (см. Тип символа).

(read-command "Command name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------

Если пользователь вводит forward-c RET, то эта функция возвращает forward-char.

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

(read-command prompt)
≡
(intern (completing-read prompt obarray
                         'commandp t nil))

Функция: read-variable prompt &optional default

Эта функция считывает имя настраиваемой переменной и возвращает её как символ. Её аргументы имеют ту же форму, что и у read-command. Она ведёт себя точно так же, как read-command, за исключением того, что она использует предикат custom-variable-p вместо commandp.

Команда: read-color &optional prompt convert allow-empty display

Эта функция считывает строку, являющуюся спецификацией цвета, либо имя цвета, либо шестнадцатеричное значение RGB, например, #RRRGGGBBB. Она использует подсказку prompt (по умолчанию: "Color (name or #RGB triplet):") и предоставляет завершение для имён цветов, но не для шестнадцатеричных значений RGB. В дополнение к именам стандартных цветов кандидаты на завершение включают цвет фона и передний план в текущей точке.

Действительные значения RGB описаны в Именах цветов.

Возвращаемое значение функции — строка, введённая пользователем в минибуфере. Однако при интерактивном вызове или если необязательный аргумент convert не nil, он преобразует любое введённое имя цвета в соответствующую строку значения RGB и возвращает именно её. Эта функция требует ввода действительной спецификации цвета. Пустые имена цветов допускаются, когда allow-empty не nil и пользователь вводит пустой ввод.

При интерактивном использовании или если display не nil, возвращаемое значение также отображается в области эха.

См. также функции read-coding-system и read-non-nil-coding-system, в Системах кодирования, выбранных пользователем, и read-input-method-name, в Методах ввода.