Форма declare

declare — это специальный макрос, который можно использовать для добавления метасвойств функции или макросу: например, пометить его как устаревший или задать особое соглашение об отступах TAB для его форм в режиме Emacs Lisp.

Макрос: declare specs…

Этот макрос игнорирует свои аргументы и возвращает nil; во время выполнения он не оказывает никакого воздействия. Однако если форма declare встречается в аргументе declare определения функции defun или defsubst (см. Определение функций) либо определения макроса defmacro (см. Определение макросов), она добавляет свойства, заданные в specs, к функции или макросу. Эта работа специально выполняется функциями defun, defsubst и defmacro.

Каждый элемент в specs должен иметь форму (property args…) и не должен быть заключён в кавычки. Эти элементы оказывают следующее действие:

(advertised-calling-convention signature when)

Действует как вызов set-advertised-calling-convention (см. Объявление функций устаревшими); signature задаёт правильный список аргументов для вызова функции или макроса, а when должно быть строкой, указывающей, когда старый список аргументов впервые был признан устаревшим.

(debug edebug-form-spec)

Допустимо только для макросов. При пошаговом выполнении макроса с помощью Edebug используйте edebug-form-spec. См. Инструментирование вызовов макросов.

(doc-string n)

Используется при определении функции или макроса, который сам будет использоваться для определения таких сущностей, как функции, макросы или переменные. Указывает, что n-й аргумент, если он есть, следует считать строкой документации.

(indent indent-spec)

Добавлять отступы в вызовах этой функции или макроса в соответствии с indent-spec. Обычно это используется для макросов, хотя подходит и для функций. См. Отступы в макросах.

(autoload-macro value)

Используется при определении макроса. Если value равно ‘expand’, любые вызовы макроса, следующие за комментарием autoload, будут предварительно развёрнуты при создании автозагрузок. Это объявление используется вместо жёстко заданных списков макросов для развёртывания в loaddefs-generate--make-autoload. См. Автозагрузка.

(interactive-only value)

Установить для свойства interactive-only функции значение value. См. Свойство interactive-only.

(obsolete current-name when)

Пометить функцию или макрос как устаревший, подобно вызову make-obsolete (см. Объявление функций устаревшими). current-name должен быть символом (в этом случае в предупреждении предлагается использовать его), строкой (с текстом предупреждения) или nil (в этом случае предупреждение не содержит дополнительных сведений). when должно быть строкой, указывающей, когда функция или макрос впервые были признаны устаревшими.

(compiler-macro expander)

Можно использовать только для функций; указывает компилятору использовать expander как функцию оптимизации. При встрече вызова функции вида (function args…) макрорасширитель вызывает expander, передавая ему эту форму, а также args…; expander может вернуть новое выражение, которое будет использовано вместо вызова функции, или вернуть исходную форму без изменений, указав тем самым, что вызов функции следует оставить как есть.

Если expander является формой lambda, её следует записать с одним аргументом (то есть в форме (lambda (arg) body)), поскольку формальные аргументы функции автоматически добавляются в список аргументов lambda.

(gv-expander expander)

Объявить expander функцией, обрабатывающей вызовы макроса (или функции) в качестве обобщённой переменной, аналогично gv-define-expander. expander может быть символом или иметь форму (lambda (arg) body); в последнем случае эта функция также получит доступ к аргументам макроса (или функции).

(gv-setter setter)

Объявить setter функцией, обрабатывающей вызовы макроса (или функции) в качестве обобщённой переменной. setter может быть символом, который будет передан в gv-define-simple-setter, или иметь форму (lambda (arg) body); в последнем случае эта функция также получит доступ к аргументам макроса (или функции) и будет передана в gv-define-setter.

(completion completion-predicate)

Задать completion-predicate в качестве функции, определяющей, следует ли включать символ функции в список функций при запросе дополнений в M-x. Эта функция-предикат вызывается только в том случае, если для read-extended-command-predicate настроено значение command-completion-default-include-p; по умолчанию значение read-extended-command-predicate равно nil (см. execute-extended-command). Предикат completion-predicate вызывается с двумя аргументами: символом функции и текущим буфером.

(modes modes)

Указать, что эту команду предполагается применять только в заданных modes. См. Указание режимов для команд.

(interactive-args arg ...)

Указать аргументы, которые следует сохранять для repeat-command. Каждый arg имеет форму argument-name form.

(pure val)

Если val не равно nil, функция является чистой (см. Что такое функция?). Это то же самое, что свойство pure символа функции (см. Стандартные свойства символов).

(side-effect-free val)

Если val не равно nil, функция не имеет побочных эффектов, поэтому байт-компилятор может игнорировать вызовы, результат которых не используется. Это то же самое, что свойство side-effect-free символа функции; см. Стандартные свойства символов.

(important-return-value val)

Если val не равно nil, байт-компилятор будет предупреждать о вызовах этой функции, в которых возвращаемое значение не используется. Это то же самое, что свойство important-return-value символа функции; см. Стандартные свойства символов.

(speed n)

Задать значение native-comp-speed, действующее при нативной компиляции этой функции (см. Переменные нативной компиляции). Это позволяет управлять уровнем оптимизации, используемым при генерации нативного кода для функции. В частности, если n равно −1, при нативной компиляции функции вместо нативного кода будет создан байт-код.

(safety n)

Задать значение compilation-safety, действующее для этой функции. Это позволяет управлять на уровне функции уровнем безопасности кода, создаваемого для неё (см. Переменные нативной компиляции).

(ftype type &optional function)

Объявить type типом этой функции. Этот тип используется describe-function в документации, а нативным компилятором (см. Компиляция Lisp в нативный код) — для оптимизации генерации кода и вывода типов. Неверные объявления типов могут привести к сбоям в нативно скомпилированном коде (см. ниже). В справке, вызываемой нажатием C-h C-f, функции с объявленными типами отмечаются как имеющие объявленный тип, в отличие от функций без таких объявлений, тип которых является выведенным.

type — это спецификатор типа (см. Спецификаторы типов) формы (function (arg-1-type … arg-n-type) RETURN-TYPE). Типы аргументов можно чередовать с &optional и &rest, чтобы отразить соглашение о вызовах функции (см. Особенности списков аргументов).

function, если указан, должен быть именем определяемой функции.

Ниже приведён пример использования ftype внутри declare для определения функции positive-p, которая принимает аргумент типа number и возвращает значение типа boolean:

(defun positive-p (x)
  (declare (ftype (function (number) boolean)))
  (when (> x 0)
    t))

Аналогично, следующий пример определяет функцию cons-or-number, которая принимает первый аргумент типа cons или number, второй необязательный аргумент типа string и возвращает один из символов is-cons или is-number:

(defun cons-or-number (x &optional err-msg)
  (declare (ftype (function ((or cons number) &optional string)
			    (member is-cons is-number))))
  (if (consp x)
      'is-cons
    (if (numberp x)
	'is-number
      (error (or err-msg "Unexpected input")))))

Описание дополнительных типов см. в разделе Типы данных Lisp).

Объявление функции с неверным типом приводит к неопределённому поведению. Если такая функция компилируется нативно при значении compilation-safety, равном нулю (см. compilation-safety), это может привести к неправильному выполнению или даже к аварийному завершению Emacs при загрузке скомпилированного кода. Чтобы избежать этих проблем, при переопределении функции с объявленным типом или добавлении к ней советов необходимо сохранять исходную сигнатуру.

no-font-lock-keyword

Допустимо только для макросов. Макросы с этим объявлением подсвечиваются font-lock (см. Режим Font Lock) как обычные функции, а не выделяются особым образом как макросы.