Список спецификации

Список спецификации необходим для спецификации Edebug, если одни аргументы вызова макроса вычисляются, а другие — нет. Некоторые элементы списка спецификации соответствуют одному или нескольким аргументам, тогда как другие изменяют обработку всех последующих элементов. Последние называются ключевыми словами спецификации и представляют собой символы, начинающиеся с «&» (например, &optional).

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

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

Спецификации Edebug обладают возможностями сопоставления регулярных выражений, а также некоторыми конструкциями контекстно-свободных грамматик: сопоставлением подсписков со сбалансированными скобками, рекурсивной обработкой форм и рекурсией посредством косвенных спецификаций.

Ниже приведена таблица возможных элементов списка спецификации и их значений (примеры, на которые даются ссылки, см. в разделе Примеры спецификаций):

sexp

Один невычисляемый объект Lisp, для которого не устанавливается инструментирование. Если макрос вычисляет аргумент во время раскрытия макроса, следует использовать для него sexp вместо form.

form

Одно вычисляемое выражение, для которого устанавливается инструментирование. Если макрос оборачивает выражение в lambda перед его вычислением, используйте вместо этого def-form. См. ниже def-form.

place

Обобщённая переменная. См. раздел Обобщённые переменные.

body

Сокращение для &rest form. См. ниже &rest. Если макрос оборачивает свой блок кода в lambda перед его вычислением, используйте вместо этого def-body. См. ниже def-body.

lambda-expr

Лямбда-выражение без кавычек.

&optional

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

Чтобы сделать необязательными только несколько элементов, за которыми следуют обязательные элементы, используйте [&optional specs…]. Чтобы указать, что должны совпасть все несколько элементов либо ни один из них, используйте &optional [specs…]. См. пример defun.

&rest

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

Чтобы повторять только несколько элементов, используйте [&rest specs…]. Чтобы указать несколько элементов, которые должны совпадать при каждом повторении, используйте &rest [specs…].

&or

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

Каждый элемент списка после &or является отдельной альтернативой. Чтобы сгруппировать два или более элемента списка в одну альтернативу, заключите их в […].

&not

Каждый из последующих элементов сопоставляется как альтернатива, как если бы использовался &or, но если совпадёт любой из них, спецификация завершится неудачей. Если не совпадёт ни один из них, ничего не сопоставляется, но спецификация &not завершается успешно.

&define

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

Сама определяющая форма не инструментируется (то есть Edebug не останавливается до и после определяющей формы), однако формы внутри неё обычно инструментируются. Ключевое слово &define должно быть первым элементом спецификации списка.

nil

Сопоставление завершается успешно, если на текущем уровне списка аргументов не осталось аргументов; в противном случае оно завершается неудачей. См. спецификации подсписков и пример с обратными кавычками.

gate

Аргумент не сопоставляется, но при сопоставлении оставшейся части спецификаций на этом уровне возврат назад через этот барьер отключён. Это используется главным образом для формирования более точных сообщений об ошибках синтаксиса. Подробнее см. раздел Возврат назад в спецификациях. См. также пример let.

&error

После &error в edebug-spec должна следовать строка — сообщение об ошибке; она прерывает инструментирование и отображает сообщение в минибуфере.

&interpose

Позволяет функции управлять разбором оставшегося кода. Имеет вид &interpose spec fun args... и означает, что сначала Edebug сопоставит spec с кодом, а затем вызовет fun, передав ей код, совпавший с spec, функцию разбора pf и, наконец, args.... Функция разбора ожидает один аргумент, указывающий список спецификации для разбора оставшегося кода. Её следует вызвать ровно один раз; она возвращает инструментированный код, который должна вернуть fun. Например, (&interpose symbolp pcase--match-pat-args) сопоставляет S-выражения, первый элемент которых является символом, а затем позволяет pcase--match-pat-args найти спецификации, связанные с этим головным символом, согласно pcase--match-pat-args, и передать их функции pf, полученной в качестве аргумента.

other-symbol

Любой другой символ в списке спецификации может быть предикатом или косвенной спецификацией.

Если для символа задана спецификация Edebug, эта косвенная спецификация должна быть либо спецификацией списка, используемой вместо символа, либо функцией, вызываемой для обработки аргументов. Спецификацию можно определить с помощью def-edebug-elem-spec:

Функция: def-edebug-elem-spec element specification

Определяет specification, используемую вместо символа element. specification должен быть списком.

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

К подходящим предикатам относятся symbolp, integerp, stringp, vectorp и atom.

[elements…]

Вектор элементов объединяет их в одну спецификацию группы. Её значение никак не связано с векторами.

"string"

Аргументом должен быть символ с именем string. Эта спецификация эквивалентна символу в кавычках 'symbol, где имя symbol — это string, однако предпочтительна форма со строкой.

(vector elements…)

Аргументом должен быть вектор, элементы которого должны соответствовать elements в спецификации. См. пример с обратными кавычками.

(elements…)

Любой другой список является спецификацией подсписка, и аргумент должен быть списком, элементы которого соответствуют спецификации elements.

Спецификация подсписка может быть точечным списком, и соответствующий аргумент-список тогда также может быть точечным списком. В качестве альтернативы последний CDR точечной спецификации списка может быть другой спецификацией подсписка (через группировку или косвенную спецификацию, например (spec . [(more specs…)])), элементы которой соответствуют аргументам неточечного списка. Это полезно в рекурсивных спецификациях, например в примере с обратными кавычками. См. также приведённое выше описание спецификации nil, используемой для завершения такой рекурсии.

Обратите внимание: спецификация подсписка, записанная как (specs . nil), эквивалентна (specs), а (specs . (sublist-elements…)) эквивалентна (specs sublist-elements…).

Ниже приведён список дополнительных спецификаций, которые могут встречаться только после &define. См. пример defun.

&name

Извлекает из кода имя текущей определяющей формы. Имеет вид &name [prestring] spec [poststring] fun args... и означает, что Edebug сопоставит spec с кодом, а затем вызовет fun, передав ей объединение текущего имени, args..., prestring, кода, совпавшего с spec, и poststring. Если fun не указана, по умолчанию используется функция, объединяющая аргументы (с @ между предыдущим именем и новым).

name

Аргумент — символ, представляющий имя определяющей формы. Сокращение для [&name symbolp].

Определяющая форма не обязана иметь поле имени; также в ней может быть несколько полей имени.

arg

Аргумент — символ, представляющий имя аргумента определяющей формы. Однако ключевые слова списка лямбда-параметров (символы, начинающиеся с «&») не допускаются.

lambda-list

Эта спецификация сопоставляет список лямбда-параметров — список аргументов лямбда-выражения.

def-body

Аргумент — блок кода в определении. Эта спецификация похожа на body, описанную выше, однако тело определения должно инструментироваться с помощью другого вызова Edebug, который ищет информацию, связанную с определением. Используйте def-body для списка форм верхнего уровня в определении.

def-form

Аргумент — одна форма верхнего уровня в определении. Эта спецификация похожа на def-body, за исключением того, что используется для сопоставления одной формы, а не списка форм. В частном случае def-form также означает, что при выполнении формы не выводится информация трассировки. См. пример interactive.