Примитивы для работы с советами

Макрос: add-function where place function &optional props

Этот макрос — удобный способ добавить совет function к функции, хранящейся в place (см. Обобщённые переменные).

where определяет, как function сочетается с существующей функцией, например, должна ли function вызываться до или после исходной функции. Список доступных способов объединения двух функций см. в разделе Способы объединения советов.

При изменении переменной (имя которой обычно оканчивается на -function) можно выбрать, будет ли function использоваться глобально или только в текущем буфере: если place — просто символ, то function добавляется к глобальному значению place. Если же place имеет вид (local symbol), где symbol — выражение, возвращающее имя переменной, то function будет добавлена только в текущем буфере. Наконец, для изменения лексической переменной необходимо использовать (var variable).

Каждую функцию, добавленную с помощью add-function, можно сопроводить списком свойств props. В настоящее время особое значение имеют только два из этих свойств:

name

Задаёт имя совета, которое remove-function может использовать для определения удаляемой функции. Обычно применяется, когда function — анонимная функция.

depth

Задаёт порядок советов, если их несколько. По умолчанию глубина равна 0. Глубина 100 означает, что этот совет следует поместить как можно глубже, тогда как глубина −100 означает, что он должен оставаться самым внешним. Если глубина двух советов одинакова, последним добавленный совет будет внешним.

Для советов :before быть внешним означает, что этот совет будет выполняться первым, до всех остальных советов; быть внутренним означает, что он будет выполняться непосредственно перед исходной функцией, без других советов между ним и исходной функцией. Аналогично, для советов :after быть внутренним означает, что совет будет выполняться сразу после исходной функции, без других советов между ними; быть внешним означает, что он будет выполнен в самом конце, после всех остальных советов. Внутренний совет :override переопределяет только исходную функцию, и к нему применяются остальные советы; внешний совет :override переопределяет не только исходную функцию, но и все остальные применённые к ней советы.

Если function не является интерактивной, объединённая функция наследует интерактивную спецификацию исходной функции, если она есть. В противном случае объединённая функция будет интерактивной и будет использовать интерактивную спецификацию function. Есть одно исключение: если интерактивная спецификация function является функцией (то есть выражением lambda или символом fbound, а не выражением или строкой), интерактивная спецификация объединённой функции будет вызовом этой функции, которому в качестве единственного аргумента передаётся интерактивная спецификация исходной функции. Чтобы интерпретировать спецификацию, полученную в качестве аргумента, используйте advice-eval-interactive-spec.

Примечание. Интерактивная спецификация function будет применяться к объединённой функции и поэтому должна соответствовать соглашению о вызове объединённой функции, а не function. Во многих случаях это не имеет значения, поскольку соглашения совпадают, однако для :around, :filter-args и :filter-return это важно: в этих случаях function получает аргументы, отличные от аргументов исходной функции, хранящейся в place.

Макрос: remove-function place function

Этот макрос удаляет function из функции, хранящейся в place. Это работает, только если function была добавлена к place с помощью add-function.

function сравнивается с функциями, добавленными к place с помощью equal, чтобы макрос работал и с лямбда-выражениями. Кроме того, она сравнивается со свойством name функций, добавленных к place; это может быть надёжнее, чем сравнение лямбда-выражений с помощью equal.

Функция: advice-function-member-p advice function-def

Возвращает значение, отличное от nil, если advice уже входит в function-def. Как и в случае с remove-function выше, вместо самой функции в качестве advice можно передать name совета.

Функция: advice-function-mapc f function-def

Вызывает функцию f для каждого совета, добавленного к function-def. Функция f вызывается с двумя аргументами: функцией-советом и её свойствами.

Функция: advice-eval-interactive-spec spec

Вычисляет интерактивную спецификацию spec так же, как при интерактивном вызове функции с такой спецификацией, а затем возвращает соответствующий список сформированных аргументов. Например, (advice-eval-interactive-spec "r\nP") вернёт список из трёх элементов, содержащий границы области и текущий аргумент префикса.

Например, если вы хотите, чтобы команда C-x m (compose-mail) запрашивала заголовок «From:», можно написать примерно следующее:

(defun my-compose-mail-advice (&rest _)
  "Read From: address interactively."
  (interactive
   (lambda (spec)
     (let* ((user-mail-address
             (completing-read "From: "
                              '("one.address@example.net"
                                "alternative.address@example.net")))
            (from (message-make-from user-full-name
                                     user-mail-address))
            (spec (advice-eval-interactive-spec spec)))
       ;; Put the From header into the OTHER-HEADERS argument.
       (push (cons 'From from) (nth 2 spec))
       spec)))
  ;; This body is not used.
  nil)

(advice-add 'compose-mail :interactive-only #'my-compose-mail-advice)