Чтение текстовых строк с помощью минибуфера

Наиболее базовая функция для ввода в минибуфере — read-from-minibuffer, которая может быть использована для чтения либо строки, либо Lisp-объекта в текстовой форме. Функция read-regexp используется для чтения регулярных выражений (см. Регулярные выражения), которые представляют собой особый вид строк. Также существуют специализированные функции для чтения команд, переменных, имён файлов и т. д. (см. Заполнение).

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

Функция: read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method

Эта функция — наиболее общий способ получения ввода из минибуфера. По умолчанию она принимает произвольный текст и возвращает его как строку; однако, если read не nil, она использует read для преобразования текста в Lisp-объект (см. Функции ввода).

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

Когда пользователь вводит команду для выхода из минибуфера, read-from-minibuffer строит возвращаемое значение из текста в минибуфере. Обычно она возвращает строку, содержащую этот текст. Однако, если read не nil, read-from-minibuffer считывает текст и возвращает полученный Lisp-объект, не вычисляя его. (См. Функции ввода для информации о чтении).

Аргумент default указывает значения по умолчанию, доступные через команды истории. Он должен быть строкой, списком строк или nil. Строка или строки становятся «будущей историей» минибуфера, доступной пользователю с помощью M-n.

Если read не nil, то default также используется как вход для read, если пользователь вводит пустой ввод. Если default является списком строк, используется первая строка. Если default — nil, пустой ввод приводит к ошибке end-of-file. Однако в обычном случае (где read — nil), read-from-minibuffer игнорирует default при вводе пустого ввода и возвращает пустую строку, "". В этом отношении она отличается от всех других функций ввода минибуфера в этой главе.

Если keymap не nil, этот keymap используется в качестве локального keymap в минибуфере. Если keymap опущен или nil, значение minibuffer-local-map используется в качестве keymap. Указание keymap — наиболее важный способ настройки минибуфера для различных приложений, таких как автодополнение.

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

Если переменная minibuffer-allow-text-properties не nil, то возвращаемая строка включает в себя любые текстовые свойства, присутствующие в минибуфере. В противном случае все текстовые свойства удаляются при возвращении значения.

Текстовые свойства в minibuffer-prompt-properties применяются к подсказке. По умолчанию этот список свойств определяет используемый стиль для подсказки. Этот стиль, если он есть, применяется к концу списка стилей и объединяется перед отображением.

Если пользователь хочет полностью контролировать вид подсказки, наиболее удобный способ — указать стиль default в конце всех списков стилей. Например:

(read-from-minibuffer
 (concat
  (propertize "Bold" 'face '(bold default))
  (propertize " and normal: " 'face '(default))))

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

Использование initial в основном устарело; мы рекомендуем использовать ненулевое значение только в сочетании с указанием ячейки cons для history. См. Начальный ввод.

Функция: read-string prompt &optional initial history default inherit-input-method

Эта функция считывает строку из минибуфера и возвращает её. Аргументы prompt, initial, history и inherit-input-method используются так же, как в read-from-minibuffer. Используемый keymap — minibuffer-local-map.

Необязательный аргумент default используется так же, как в read-from-minibuffer, за исключением того, что, если он не nil, он также задаёт значение по умолчанию для возврата, если пользователь вводит пустой ввод. Как и в read-from-minibuffer, он должен быть строкой, списком строк или nil, что эквивалентно пустой строке. Если default — строка, эта строка является значением по умолчанию. Если это список строк, первой строкой является значение по умолчанию. (Все эти строки доступны пользователю в «будущей истории минибуфера».)

Эта функция работает, вызывая функцию read-from-minibuffer:

(read-string prompt initial history default inherit)
≡
(let ((value
       (read-from-minibuffer prompt initial nil nil
                             history default inherit)))
  (if (and (equal value "") default)
      (if (consp default) (car default) default)
    value))

Функция: read-regexp prompt &optional defaults history

Эта функция считывает регулярное выражение как строку из минибуфера и возвращает его. Если строка подсказки минибуфера prompt не заканчивается на ‘:’ (за которым следует необязательное пробельное пространство), функция добавляет ‘: ’ в конец, перед значением по умолчанию (см. ниже), если оно не пустое.

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

Если defaults — символ, read-regexp обращается к значению переменной read-regexp-defaults-function (см. ниже), и если оно не nil, использует его вместо defaults. В этом случае значение должно быть либо:

• - regexp-history-last, что означает использование первого элемента соответствующего списка истории минибуфера (см. ниже).
• - Функцией без аргументов, значение которой (которое должно быть nil, строкой или списком строк) становится значением defaults.

read-regexp теперь гарантирует, что результатом обработки defaults является список (т. е. если значение — nil или строка, оно преобразуется в список из одного элемента). К этому списку read-regexp затем добавляются несколько потенциально полезных кандидатов на ввод. Это:

• - Слово или символ в позиции курсора.
• - Последнее регулярное выражение, используемое в инкрементальном поиске.
• - Последняя строка, используемая в инкрементальном поиске.
• - Последняя строка или шаблон, используемые в командах замены запросов.

Функция теперь имеет список регулярных выражений, которые она передаёт в read-from-minibuffer для получения ввода пользователя. Первый элемент списка — результат по умолчанию в случае пустого ввода. Все элементы списка доступны пользователю как список «будущей истории минибуфера» (см. будущий список в Руководстве по GNU Emacs).

Необязательный аргумент history, если он не nil, — символ, указывающий на список истории минибуфера для использования (см. История минибуфера). Если он опущен или nil, список истории по умолчанию — regexp-history.

Пользовательский параметр: read-regexp-defaults-function

Функция read-regexp может использовать значение этой переменной для определения своего списка регулярных выражений по умолчанию. Если оно не nil, значение этой переменной должно быть либо:

• - Символом regexp-history-last.
• - Функцией без аргументов, которая возвращает либо nil, строку или список строк.

См. read-regexp выше для получения подробностей о том, как используются эти значения.

Переменная: minibuffer-allow-text-properties

Если эта переменная nil, то read-from-minibuffer и read-string удаляют все текстовые свойства из ввода минибуфера перед его возвратом. Однако read-no-blanks-input (см. ниже), а также read-minibuffer и связанные с ним функции (см. Чтение Lisp-объектов с помощью минибуфера), и все функции, которые выполняют ввод минибуфера с автодополнением, удаляют свойство face безусловно, независимо от значения этой переменной.

Если эта переменная не nil, большинство текстовых свойств строк из таблицы автодополнения сохраняются — но только на той части строк, которая была дополнена.

(let ((minibuffer-allow-text-properties t))
  (completing-read "String: " (list (propertize "foobar" 'data 'zot))))
=> #("foobar" 3 6 (data zot))

В этом примере пользователь ввёл ‘foo’ и нажал клавишу TAB, поэтому текстовые свойства сохраняются только на последних трёх символах.

Переменная: minibuffer-local-map

Это локальный keymap по умолчанию для чтения из минибуфера. По умолчанию он создаёт следующие привязки:

C-j

exit-minibuffer

RET

exit-minibuffer

M-<

minibuffer-beginning-of-buffer

C-g

abort-recursive-edit

M-n

DOWN

next-history-element

M-p

UP

previous-history-element

M-s

next-matching-history-element

M-r

previous-matching-history-element

Функция: read-no-blanks-input prompt &optional initial inherit-input-method

Эта функция считывает строку из минибуфера, но не допускает пробельных символов в качестве части входных данных: вместо этого эти символы завершают ввод. Аргументы prompt, initial и inherit-input-method используются так же, как в read-from-minibuffer.

Это упрощённый интерфейс для функции read-from-minibuffer, и она передаёт значение ключевой карты minibuffer-local-ns-map в качестве аргумента keymap для этой функции. Поскольку ключевая карта minibuffer-local-ns-map не переопределяет C-q, возможно вставить пробел в строку, поместив его в кавычки.

Эта функция отбрасывает свойства текста, независимо от значения minibuffer-allow-text-properties.

(read-no-blanks-input prompt initial)
≡
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer prompt initial minibuffer-local-ns-map))

Переменная: minibuffer-local-ns-map

Эта встроенная переменная — это ключевая карта, используемая в качестве локальной ключевой карты минибуфера в функции read-no-blanks-input. По умолчанию она устанавливает следующие привязки, помимо тех, что определены в minibuffer-local-map:

SPC

exit-minibuffer

TAB

exit-minibuffer

?

self-insert-and-exit

Функция: format-prompt prompt default &rest format-args

Форматирует prompt со значением по умолчанию default в соответствии с переменной minibuffer-default-prompt-format.

minibuffer-default-prompt-format — это строка форматирования (по умолчанию ‘" (default %s)"’), которая определяет, как форматируется часть «по умолчанию» в подсказках, таких как ‘"Локальное имя файла (по умолчанию somefile): "’.

Для того, чтобы пользователи могли настроить отображение, код, который запрашивает у пользователя значение (и имеет значение по умолчанию), должен выглядеть примерно так:

(read-file-name
 (format-prompt "Local filename" file)
 nil file)

Если format-args равно nil, prompt используется как строка. Если format-args не nil, prompt используется как строка управления форматированием, и prompt и format-args передаются в format (см. Форматирование строк).

minibuffer-default-prompt-format может быть ‘""’, в этом случае значения по умолчанию не отображаются.

Если default равно nil, значение по умолчанию отсутствует, и, следовательно, строка «значения по умолчанию» не включена в результирующее значение. Если default — это список, не являющийся nil, используется первый элемент списка в подсказке.

Переменная: read-minibuffer-restore-windows

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

Если этот параметр равен nil, такие восстановления не выполняются. Следовательно, разделение окна, упомянутое выше, сохранится после выхода из минибуфера.