---

1.3.7.1 Описание функции-пример

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

Появление ключевого слова &optional в списке аргументов указывает на то, что последующие аргументы могут быть опущены (опущенные аргументы по умолчанию равны nil). Не следует писать &optional, когда вызываете функцию.

Ключевое слово &rest (которое должно сопровождаться одним именем аргумента) указывает на то, что может следовать любое количество аргументов. Одно имя аргумента после &rest получает в качестве значения список всех оставшихся аргументов, переданных функции. Не следует писать &rest, когда вызываете функцию.

Вот описание воображаемой функции foo:

Функция: foo integer1 &optional integer2 &rest integers ¶

Функция foo вычитает integer1 из integer2, а затем прибавляет все остальные аргументы к результату. Если integer2 не предоставлен, по умолчанию используется число 19.

(foo 1 5 3 9)
     ⇒ 16
(foo 5)
     ⇒ 14

Более обобщенно:

(foo w x y…)
≡
(+ (- x w) y…)

По соглашению, любой аргумент, в имени которого содержится имя типа (например, integer, integer1 или buffer), ожидается, что он будет этого типа. Множественное число типа (например, buffers) часто означает список объектов этого типа. Аргумент с именем object может быть любого типа. (Для списка типов объектов Emacs см. Типы данных Lisp.) Аргумент с любым другим именем (например, new-file) специфичен для функции; если у функции есть строка документации, тип аргумента должен быть описан там (см. Документация).

См. Лямбда-выражения для более полного описания аргументов, измененных &optional и &rest.

Описания команд, макросов и специальных форм имеют одинаковый формат, но слово «Функция» заменяется на «Команда», «Макрос» или «Специальная форма», соответственно. Команды — это просто функции, которые могут вызываться интерактивно; макросы обрабатывают свои аргументы иначе, чем функции (аргументы не вычисляются), но представляются одинаково.

Описания макросов и специальных форм используют более сложную нотацию для указания необязательных и повторяющихся аргументов, поскольку они могут разбивать список аргументов на отдельные аргументы более сложными способами. «[optional-arg]» означает, что optional-arg является необязательным, а «repeated-args…» означает ноль или более аргументов. Скобки используются, когда несколько аргументов сгруппированы в дополнительные уровни структуры списка. Вот пример:

Специальная форма: count-loop (var [from to [inc]]) body… ¶

Эта воображаемая специальная форма реализует цикл, который выполняет формы body, а затем увеличивает переменную var на каждой итерации. При первой итерации переменная имеет значение from; при последующих итерациях она увеличивается на единицу (или на inc, если он указан). Цикл завершается до выполнения body, если var равно to. Вот пример:

(count-loop (i 0 10)
  (prin1 i) (princ " ")
  (prin1 (aref vector i))
  (terpri))

Если from и to опущены, var связывается с nil перед началом цикла, и цикл завершается, если var не равен nil в начале итерации. Вот пример:

(count-loop (done)
  (if (pending)
      (fixit)
    (setq done t)))

В этой специальной форме аргументы from и to являются необязательными, но должны присутствовать оба или отсутствовать оба. Если они присутствуют, inc также может быть указан как необязательный. Эти аргументы сгруппированы с аргументом var в список, чтобы отличить их от body, который включает все оставшиеся элементы формы.