Функции поиска по свойствам текста

При типичном использовании свойств текста большинство времени несколько или много последовательных символов имеют одинаковое значение для свойства. Вместо того, чтобы писать программы, которые проверяют символы по одному, намного быстрее обрабатывать куски текста, которые имеют одинаковое значение свойства.

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

Для хорошей производительности очень важно использовать аргумент limit в этих функциях, особенно в тех, которые ищут одно свойство — в противном случае они могут тратить много времени на сканирование до конца буфера, если интересующее вас свойство не меняется.

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

Функция: next-property-change pos &optional object limit

Функция сканирует текст вперёд от позиции pos в строке или буфере object до тех пор, пока не обнаружит изменение какого-либо свойства текста, затем возвращает позицию изменения. Другими словами, она возвращает позицию первого символа после pos, чьи свойства не идентичны свойствам символа, находящегося сразу после pos.

Если limit не nil, то сканирование заканчивается на позиции limit. Если до этого момента изменения свойств не происходит, эта функция возвращает limit.

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

Вот пример того, как сканировать буфер по кускам текста, в пределах которых все свойства постоянны:

(while (not (eobp))
  (let ((plist (text-properties-at (point)))
        (next-change
         (or (next-property-change (point) (current-buffer))
             (point-max))))
    Process text from point to next-change…
    (goto-char next-change)))

Функция: previous-property-change pos &optional object limit

Это похоже на next-property-change, но сканирует назад от pos, а не вперёд. Если значение не nil, то это позиция, меньшая или равная pos; она равна pos только если limit равно pos.

Функция: next-single-property-change pos prop &optional object limit

Функция сканирует текст в поисках изменения свойства prop, а затем возвращает позицию изменения. Сканирование выполняется вперёд от позиции pos в строке или буфере object. Другими словами, эта функция возвращает позицию первого символа после pos, чьё свойство prop отличается от свойства символа, находящегося сразу после pos.

Если limit не nil, то сканирование заканчивается на позиции limit. Если до этого момента изменения свойства не происходит, next-single-property-change возвращает limit.

Значение равно nil, если свойство остаётся неизменным до конца object, а limit равен nil. Если значение не nil, то это позиция, большая или равная pos; она равна pos только если limit равно pos.

Функция: previous-single-property-change pos prop &optional object limit

Это похоже на next-single-property-change, но сканирует назад от pos, а не вперёд. Если значение не nil, то это позиция, меньшая или равная pos; она равна pos только если limit равно pos.

Функция: next-char-property-change pos &optional limit

Это похоже на next-property-change за исключением того, что она учитывает наложение свойств, а также свойства текста, и если изменение не найдено до конца буфера, возвращает максимальную позицию буфера, а не nil (в этом смысле она похожа на соответствующую функцию наложения next-overlay-change, а не на next-property-change). Нет операнда object, так как эта функция работает только с текущим буфером. Она возвращает следующий адрес, на котором изменяется тот или иной вид свойств.

Функция: previous-char-property-change pos &optional limit

Это похоже на next-char-property-change, но сканирует назад от pos, а не вперёд, и возвращает минимальную позицию буфера, если изменение не найдено.

Функция: next-single-char-property-change pos prop &optional object limit

Это похоже на next-single-property-change за исключением того, что она учитывает наложение свойств, а также свойства текста, и если изменение не найдено до конца object, возвращает максимальную допустимую позицию в object, а не nil. В отличие от next-char-property-change, эта функция имеет операнд object; если object не буфер, рассматриваются только свойства текста.

Функция: previous-single-char-property-change pos prop &optional object limit

Это похоже на next-single-char-property-change, но сканирует назад от pos, а не вперёд, и возвращает минимальную допустимую позицию в object, если изменение не найдено.

Функция: text-property-any start end prop value &optional object

Эта функция возвращает не-nil, если по крайней мере один символ между start и end имеет свойство prop, значение которого равно value. Более точно, она возвращает позицию первого такого символа. В противном случае она возвращает nil.

Необязательный пятый аргумент object указывает строку или буфер для сканирования. Позиции относительны к object. По умолчанию object — это текущий буфер.

Функция: text-property-not-all start end prop value &optional object

Эта функция возвращает не-nil, если по крайней мере один символ между start и end не имеет свойство prop со значением value. Более точно, она возвращает позицию первого такого символа. В противном случае она возвращает nil.

Необязательный пятый аргумент object указывает строку или буфер для сканирования. Позиции относительны к object. По умолчанию object — это текущий буфер.

Функция: text-property-search-forward prop &optional value predicate not-current

Искать следующий регион, в котором свойство текста prop установлено в value в соответствии с predicate.

Эта функция моделируется по search-forward и подобным, в том смысле, что она перемещает точку, но возвращает структуру, описывающую соответствие, вместо того, чтобы возвращать его в match-beginning и подобных.

Если свойство текста не найдено, функция возвращает nil. Если найдено, точка устанавливается в конце региона, имеющего это совпадение свойства текста, и возвращается структура prop-match.

predicate может быть t (что является синонимом equal), nil (что означает «не равно»), или предикатом, который будет вызван с двумя параметрами: первый — value, а второй — значение свойства текста, которое мы проверяем.

Если not-current, если точка находится в регионе, где есть совпадение, то пропустить его и найти следующий экземпляр вместо этого.

Структура prop-match имеет следующие методы доступа: prop-match-beginning (начало совпадения), prop-match-end (конец совпадения) и prop-match-value (значение property в начале совпадения).

В примерах ниже представьте, что вы находитесь в буфере, который выглядит так:

This is a bold and here's bolditalic and this is the end.

То есть слова «жирным» шрифтом имеют формат bold, а слово «курсивом» — формат italic.

При установленной точке в начале:

(while (setq match (text-property-search-forward 'face 'bold t))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

Это выберет все слова, использующие формат bold.

(while (setq match (text-property-search-forward 'face nil t))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

Это выберет все участки без свойств шрифтов, что приведёт к списку ‘("This is a " "and here's " "and this is the end")’ (только в обратном порядке, так как мы использовали push).

(while (setq match (text-property-search-forward 'face nil nil))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

Это выберет все области, где face установлено на какое-то значение, но это разделено на изменения свойств, поэтому результат здесь будет ‘("bold" "bold" "italic")’.

Для более реалистичного примера использования этой функции рассмотрим буфер, где определённые участки представляют URL-адреса, и эти адреса помечены тегом shr-url.

(while (setq match (text-property-search-forward 'shr-url nil nil))
  (push (prop-match-value match) urls))

Это даст вам список всех этих URL-адресов.

Функция: text-property-search-backward prop &optional value predicate not-current

Это точно так же, как text-property-search-backward, но поиск выполняется назад. Точка устанавливается в начале совпавшей области вместо конца.