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

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

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

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

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

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

Необязательный аргумент 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

Эта функция читает имя команды и возвращает его в виде символа Lisp. Аргумент 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, чтобы выполнять завершение по множеству существующих символов Lisp, и предикат 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 foreground face

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

Названия цветов.

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

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

Необязательные аргументы foreground и face управляют отображением кандидатов для завершения в буфере *Completions*. Кандидаты отображаются с указанным начертанием face, но разными цветами: если foreground не равен nil, цвет текста меняется на цвет кандидата, иначе цвет фона меняется на цвет кандидата.

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