Просмотр содержимого буфера

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

Функция: buffer-substring start end

Эта функция возвращает строку, содержащую копию текста области, заданной позициями start и end в текущем буфере. Если аргументы не являются позициями в доступной части буфера, buffer-substring сигнализирует об ошибке args-out-of-range.

Вот пример, предполагающий, что режим Font-Lock не включён:

---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
     ⇒ "This is t"

(buffer-substring (point-max) 10)
     ⇒ "he contents of buffer foo\n"

Если копируемый текст имеет какие-либо текстовые свойства, они копируются в строку вместе с символами, к которым относятся. См. Текстовые свойства. Однако наложения (см. Наложения) в буфере и их свойства игнорируются и не копируются.

Например, если режим Font-Lock включён, результат может выглядеть так:

(buffer-substring 1 10)
     ⇒ #("This is t" 0 1 (fontified t) 1 9 (fontified t))

Функция: buffer-substring-no-properties start end

Эта функция аналогична buffer-substring, но копирует только сами символы, без текстовых свойств. См. Текстовые свойства.

Функция: buffer-string

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

Если необходимо убедиться, что при копировании полученной строки в другое место её визуальное представление не изменится из-за изменения порядка двунаправленного текста, используйте функцию buffer-substring-with-bidi-context (см. buffer-substring-with-bidi-context).

Функция: filter-buffer-substring start end &optional delete

Эта функция фильтрует текст буфера между start и end с помощью функции, указанной переменной filter-buffer-substring-function, и возвращает результат. Порядок позиций буфера, заданных параметрами start и end, не должен иметь значения, поскольку эта функция часто используется для извлечения текста, передаваемого функциям удаления (см. Функции удаления).

Функция фильтрации по умолчанию обращается к устаревшему хуку-обёртке filter-buffer-substring-functions (подробные сведения об этой устаревшей возможности см. в строке документации макроса with-wrapper-hook). Если он равен nil, функция возвращает неизменённый текст из буфера, то есть то, что вернула бы buffer-substring.

Если delete не равен nil, функция после копирования удаляет текст между start и end, как delete-and-extract-region.

Код на Lisp должен использовать эту функцию вместо buffer-substring, buffer-substring-no-properties или delete-and-extract-region при копировании в доступные пользователю структуры данных, такие как кольцо удалений, буфер обмена X и регистры. Основные и дополнительные режимы могут изменять filter-buffer-substring-function, чтобы преобразовывать такой текст при копировании из буфера.

Переменная: filter-buffer-substring-function

Значение этой переменной — функция, которую filter-buffer-substring вызывает для выполнения основной работы. Функция получает три аргумента, такие же, как у filter-buffer-substring, и должна обрабатывать их в соответствии с документацией этой функции. Она должна возвращать отфильтрованный текст (и при необходимости удалять исходный текст). Обратите внимание, что она должна обрабатывать аргументы start и end независимо от порядка заданных ими позиций буфера, чтобы соблюдать протокол извлечения текста для его удаления.

Следующие две переменные объявлены устаревшими в пользу filter-buffer-substring-function, но по-прежнему поддерживаются для обратной совместимости.

Переменная: filter-buffer-substring-functions

Эта устаревшая переменная является хуком-обёрткой; его элементами должны быть функции, принимающие четыре аргумента: fun, start, end и delete. fun — функция, принимающая три аргумента (start, end и delete) и возвращающая строку. В обоих случаях аргументы start, end и delete совпадают с аргументами filter-buffer-substring.

Первой функции хука передаётся fun, эквивалентная стандартному действию filter-buffer-substring, то есть она возвращает подстроку буфера между start и end и при необходимости удаляет исходный текст из буфера. В большинстве случаев функция хука один раз вызывает fun, а затем обрабатывает полученный результат. Следующая функция хука получает эквивалентную ей fun и так далее. Фактическое возвращаемое значение является результатом последовательного выполнения всех функций хука.

Функция: current-word &optional strict really-word

Эта функция возвращает символ (или слово) в точке или рядом с ней в виде строки. Возвращаемое значение не содержит текстовых свойств.

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

Если необязательный аргумент strict не равен nil, точка должна находиться внутри символа или слова либо рядом с ним — если там нет символа или слова, функция возвращает nil. В противном случае подходит близлежащий символ или слово в той же строке.

Функция: thing-at-point thing &optional no-properties

Возвращает в виде строки объект thing, находящийся в точке или рядом с ней.

Аргумент thing — символ, задающий тип синтаксической сущности. Возможные значения включают symbol, list, sexp, defun, filename, existing-filename, url, word, sentence, whitespace, line, page, string и другие.

Если необязательный аргумент no-properties не равен nil, эта функция удаляет текстовые свойства из возвращаемого значения.

---------- Buffer: foo ----------
Gentlemen may cry ``Pea∗ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
     ⇒ "Peace"
(thing-at-point 'line)
     ⇒ "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     ⇒ nil

Переменная: thing-at-point-provider-alist

Эта переменная позволяет пользователям и режимам настраивать работу thing-at-point. Это ассоциативный список объектов thing и функций (вызываемых без параметров), возвращающих соответствующий объект. Элементы для thing проверяются по очереди, пока не будет возвращён результат, отличный от nil.

Например, основной режим может задать следующее:

(setq-local thing-at-point-provider-alist
            (append thing-at-point-provider-alist
                    '((url . my-mode--url-at-point))))

Если ни один поставщик не возвращает значение, отличное от nil, объект thing вычисляется стандартным способом.