Временные отображения используются программами на Lisp для вывода данных в буфер и последующего представления их пользователю для ознакомления, а не для редактирования. Многие команды справки используют эту возможность.
Этот макрос выполняет формы из body, организуя вставку всего выводимого ими материала в буфер с именем buffer-name, который при необходимости сначала создаётся и переводится в режим Help. (Смотрите аналогичную форму with-temp-buffer-window ниже.) Наконец, буфер отображается в некотором окне, но это окно не выбирается.
Если формы в body не изменяют основной режим в выходном буфере, так что по завершении их выполнения он всё ещё находится в режиме Help, то with-output-to-temp-buffer делает этот буфер в конце доступным только для чтения, а также сканирует его на предмет имён функций и переменных, чтобы превратить их в кликабельные перекрёстные ссылки. Смотрите Советы по строкам документации, в частности пункт о гиперссылках в строках документации, для получения более подробной информации.
Строка buffer-name задаёт временный буфер; он не обязан уже существовать. Аргументом должна быть строка, а не буфер. Буфер сначала очищается (без каких-либо запросов) и помечается как не изменённый после выхода из with-output-to-temp-buffer.
with-output-to-temp-buffer привязывает standard-output к временному буферу, затем вычисляет формы в body. Вывод с использованием функций вывода Lisp внутри body по умолчанию направляется в этот буфер (но вывод на экран и сообщения в области эха, хотя они и являются «выводом» в общем смысле слова, не затрагиваются). Смотрите Функции вывода.
Доступно несколько хуков для настройки поведения этой конструкции; они перечислены ниже.
Возвращается значение последней формы в body.
---------- Буфер: foo ---------- Это содержимое foo. ---------- Буфер: foo ----------
(with-output-to-temp-buffer "foo"
(print 20)
(print standard-output))
⇒ #<buffer foo>
---------- Буфер: foo ----------
20
#<buffer foo>
---------- Буфер: foo ----------
Если эта переменная не равна nil, with-output-to-temp-buffer вызывает её как функцию для выполнения задачи отображения буфера справки. Функция получает один аргумент — буфер, который она должна отобразить.
Желательно, чтобы эта функция запускала temp-buffer-show-hook так же, как это обычно делает with-output-to-temp-buffer, внутри save-selected-window и с выбранными окном и буфером.
Этот нормальный хук запускается with-output-to-temp-buffer перед вычислением body. Когда хук выполняется, текущим является временный буфер. Этот хук обычно настраивается с помощью функции для перевода буфера в режим Help.
Этот нормальный хук запускается with-output-to-temp-buffer после отображения временного буфера. Когда хук выполняется, текущим является временный буфер, а окно, в котором он был отображён, выбрано.
Этот макрос похож на with-output-to-temp-buffer. Как и та конструкция, он выполняет body, организуя вставку любого выводимого материала в буфер с именем buffer-or-name, и отображает этот буфер в некотором окне. Однако, в отличие от with-output-to-temp-buffer, он не переключает этот буфер в режим Help автоматически.
Аргумент buffer-or-name задаёт временный буфер. Он может быть либо буфером (который уже должен существовать), либо строкой, в этом случае буфер с таким именем создаётся при необходимости. Буфер помечается как не изменённый и доступный только для чтения при выходе из with-temp-buffer-window.
Этот макрос не вызывает temp-buffer-show-function. Вместо этого он передаёт аргумент action функции display-buffer (см. Выбор окна для отображения буфера) для отображения буфера.
Возвращается значение последней формы в body, если только не указан аргумент quit-function. В этом случае он вызывается с двумя аргументами: окно, показывающее буфер, и результат body. Тогда итоговым возвращаемым значением будет то, что возвращает quit-function.
Этот макрос использует нормальные хуки temp-buffer-window-setup-hook и temp-buffer-window-show-hook вместо аналогичных хуков, запускаемых with-output-to-temp-buffer.
Две описанные ниже конструкции в основном идентичны with-temp-buffer-window, но отличаются от него следующим образом:
Этот макрос похож на with-temp-buffer-window, но в отличие от него делает буфер, указанный buffer-or-name, текущим во время выполнения body.
Окно, показывающее временный буфер, можно подогнать под размер этого буфера, используя следующий режим:
Когда этот второстепенный режим включён, окна, показывающие временный буфер, автоматически изменяют размер в соответствии с содержимым буфера.
Размер окна изменяется тогда и только тогда, когда оно было специально создано для этого буфера. В частности, окна, в которых ранее отображался другой буфер, изменению размера не подлежат. По умолчанию этот режим использует fit-window-to-buffer (см. Изменение размера окон) для изменения размера. Вы можете указать другую функцию, настроив опции temp-buffer-max-height и temp-buffer-max-width ниже.
Действие этой опции можно переопределить, указав подходящую запись alist действий window-height, window-width или window-size для display-buffer (см. Alist действий для отображения буфера).
Эта опция задаёт максимальную высоту (в строках) окна, отображающего временный буфер, когда включён temp-buffer-resize-mode. Она также может быть функцией, вызываемой для выбора высоты для такого буфера. Она получает один аргумент — буфер, и должна возвращать положительное целое число. Во время вызова функции окно, размер которого изменяется, выбрано.
Эта опция задаёт максимальную ширину окна (в столбцах), отображающего временный буфер, когда включён temp-buffer-resize-mode. Она также может быть функцией, вызываемой для выбора ширины для такого буфера. Она получает один аргумент — буфер, и должна возвращать положительное целое число. Во время вызова функции окно, размер которого изменяется, выбрано.
Следующая функция использует текущий буфер для временного отображения:
Эта функция кратковременно отображает string в текущем буфере в позиции position. Она не влияет на список отмены и на статус модификации буфера.
Кратковременное отображение сохраняется до следующего события ввода. Если следующим событием ввода является char, momentary-string-display игнорирует его и возвращает управление. В противном случае это событие остаётся в буфере для последующего использования в качестве ввода. Таким образом, набор char просто удалит строку с экрана, а набор (скажем) C-f удалит строку с экрана и впоследствии (предположительно) переместит точку вперёд. Аргумент char по умолчанию равен пробелу.
Возвращаемое значение momentary-string-display не имеет смысла.
Если строка string не содержит управляющих символов, вы можете выполнить ту же задачу более общим способом, создав (а затем удалив) наложение со свойством before-string. Смотрите Свойства наложений.
Если message не равен nil, он отображается в области эха, пока string отображается в буфере. Если он равен nil, отображается сообщение по умолчанию о том, что нужно нажать char для продолжения.
В этом примере точка изначально находится в начале второй строки:
---------- Буфер: foo ---------- Это содержимое foo. ∗Вторая строка. ---------- Буфер: foo ----------
(momentary-string-display "**** Важное сообщение! ****" (point) ?\r "Нажмите RET по окончании чтения") ⇒ t
---------- Буфер: foo ---------- Это содержимое foo. **** Важное сообщение! ****Вторая строка. ---------- Буфер: foo ---------- ---------- Область эха ---------- Нажмите RET по окончании чтения ---------- Область эха ----------