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

Самый простой примитив для ввода в минибуфере — 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. Кроме того, если вызов предоставляет завершение ввода (например, с помощью аргумента keymap), варианты завершения добавляются в «будущую историю», когда значения в default исчерпаны с помощью M-n; см. minibuffer-default-add-function.

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

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

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

Если переменная minibuffer-allow-text-properties не равна nil и привязана через let или локальна для буфера минибуфера, возвращаемая строка включает все свойства текста, имевшиеся в минибуфере. В противном случае при возврате значения все свойства текста удаляются. (По умолчанию эта переменная равна 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 в основном считается устаревшим; рекомендуется применять значение, отличное от nil, только вместе с указанием конс-ячейки для history. См. Начальный ввод.

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

Эта функция читает строку из минибуфера и возвращает её. Аргументы prompt, initial, history и inherit-input-method используются так же, как в read-from-minibuffer. Используется карта клавиш 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-string может оказаться не лучшим вариантом. В таком случае удобнее открыть новый обычный буфер, в котором пользователь сможет редактировать строку; для этого можно использовать функцию read-string-from-buffer.

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

Пользователь может использовать команду M-s c, чтобы указать, следует ли учитывать регистр. Если пользователь воспользовался этой командой, возвращаемой строке будет задано свойство текста case-fold со значением fold или inhibit-fold. Вызывающая read-regexp сторона сама должна использовать это значение; для этого предусмотрена вспомогательная функция read-regexp-case-fold-search. Типичный пример использования может выглядеть так:

(let* ((regexp (read-regexp "Search for: "))
       (case-fold-search (read-regexp-case-fold-search regexp)))
  (re-search-forward regexp))

Пользовательская настройка: read-regexp-defaults-function

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

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

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

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

Если эта переменная равна nil, как и задано по умолчанию, то read-from-minibuffer и все функции, выполняющие ввод в минибуфере, удаляют все свойства текста из введённых данных перед их возвратом.

Однако read-minibuffer и связанные с ней функции (см. Чтение объектов Lisp с помощью минибуфера) безусловно удаляют свойства текста независимо от значения этой переменной.

Если эта переменная не равна nil и привязана через let или локальна для буфера минибуфера, то read-from-minibuffer, read-string и все связанные с ними функции сохраняют свойства текста. Однако функции, выполняющие ввод в минибуфере с завершением, удаляют свойство face, сохраняя остальные свойства текста.

(minibuffer-with-setup-hook
    (lambda ()
      (setq-local minibuffer-allow-text-properties t))
  (completing-read
   "String: " (list (propertize "foobar" 'face 'baz 'data 'zot))))
=> #("foobar" 0 6 (data zot))

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

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

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

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

Переменная minibuffer-mode-map является псевдонимом этой переменной.

Функция: 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-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)"’), задающая форматирование фрагмента «значение по умолчанию» в подсказках вида ‘"Local filename (default 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, в подсказке используется первый элемент списка.

И prompt, и minibuffer-default-prompt-format обрабатываются функцией substitute-command-keys (см. Подстановка привязок клавиш в документации).

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

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

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