Автозагрузка

Функция autoload позволяет зарегистрировать существование функции или макроса, но отложить загрузку файла, который его определяет. Первый вызов функции автоматически загружает соответствующую библиотеку, чтобы установить реальное определение и другой связанный код, а затем выполняет реальное определение так, как будто оно было загружено все время. Автозагрузка также может быть инициирована, обращаясь к документации функции или макроса (см. Основные принципы документации), и при завершении ввода имен переменных и функций (см. Автозагрузка по префиксу ниже).

Существует два способа настройки загружаемой по автозагрузке функции: вызовом autoload, и написав «магический» комментарий в исходном коде перед реальным определением. autoload является низкоуровневым примитивом для автозагрузки; любая программа на Lisp может вызвать autoload в любое время. Магические комментарии являются наиболее удобным способом сделать функцию автозагружаемой для пакетов, установленных вместе с Emacs. Эти комментарии сами по себе ничего не делают, но они служат руководством для команды update-file-autoloads, которая строит вызовы autoload и организует их выполнение при сборке Emacs.

Функция: autoload функция имя_файла &опционально строка_документации интерактивный тип

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

Если имя_файла не содержит имя каталога или суффикс .el или .elc, эта функция настаивает на добавлении одного из этих суффиксов, и она не будет загружать файл, имя которого просто имя_файла без добавленного суффикса. (Переменная load-suffixes указывает точные необходимые суффиксы.)

Аргумент строка_документации — это строка документации для функции. Указание строки документации в вызове autoload позволяет просмотреть документацию, не загружая реальное определение функции. Обычно это должно совпадать со строкой документации в самом определении функции. Если это не так, то строка документации из определения функции вступает в силу при её загрузке.

Если интерактивный не nil, это означает, что функция может вызываться интерактивно. Это позволяет работе автодополнения в M-x без загрузки реального определения функция. Полное интерактивное описание здесь не приводится; оно не требуется, если пользователь не вызывает функция, и когда это произойдёт, пришло время загрузить реальное определение.

Если интерактивный является списком, он интерпретируется как список режимов, для которых эта команда применима.

Вы можете автозагружать макросы и карты клавиш, а также обычные функции. Укажите тип как macro, если функция на самом деле макрос. Укажите тип как keymap, если функция на самом деле карта клавиш. Различные части Emacs должны знать эту информацию, не загружая реального определения.

Автозагружаемая карта клавиш автоматически загружается во время поиска клавиш, когда привязка префиксной клавиши является символом функция. Автозагрузка не происходит при других видах доступа к карте клавиш. В частности, она не происходит, когда программа Lisp получает карту клавиш из значения переменной и вызывает define-key; даже если имя переменной является тем же символом функция.

Если у функция уже есть ненулевое определение функции, которое не является объектом автозагрузки, эта функция ничего не делает и возвращает nil. В противном случае она создает объект автозагрузки (см. Тип автозагрузки) и сохраняет его как определение функции для функция. Объект автозагрузки имеет такой вид:

(autoload filename docstring interactive type)

Например,

(symbol-function 'run-prolog)
     ⇒ (autoload "prolog" 169681 t nil)

В этом случае, "prolog" — это имя файла для загрузки, 169681 ссылается на строку документации в файле emacs/etc/DOC (см. Основные принципы документации), t означает, что функция интерактивна, и nil означает, что она не является макросом или картой клавиш.

Функция: autoloadp объект

Эта функция возвращает не-nil, если объект является объектом автозагрузки. Например, чтобы проверить, определена ли run-prolog как автозагружаемая функция, вычислите

(autoloadp (symbol-function 'run-prolog))

Файл, загруженный по автозагрузке, обычно содержит другие определения и может потребовать или предоставить одну или несколько функций. Если файл не загружен полностью (из-за ошибки при вычислении его содержимого), любые определения функций или вызовы provide , которые произошли во время загрузки, отменяются. Это делается для того, чтобы убедиться, что при следующей попытке вызова любой функции, автозагружаемой из этого файла, будет предпринята попытка загрузки файла снова. Если этого не было, то некоторые функции в файле могли быть определены прерванной загрузкой, но не работают должным образом из-за отсутствия некоторых подпрограмм, которые не были загружены успешно, поскольку они расположены позже в файле.

Если загружаемый по автозагрузке файл не определяет желаемую функцию или макрос Lisp, то генерируется ошибка с данными "Autoloading failed to define function function-name".

Магический комментарий автозагрузки (часто называемый автозагрузовым cookie) состоит из ‘;;;###autoload’, на отдельной строке, непосредственно перед реальным определением функции в исходном файле автозагрузки. Команда M-x update-file-autoloads записывает соответствующий autoload вызов в loaddefs.el. (Строка, используемая в качестве автозагрузочного cookie и имя файла, генерируемого update-file-autoloads, могут быть изменены от указанных значений, см. ниже.) Сборка Emacs загружает loaddefs.el, а следовательно, вызывает autoload. M-x make-directory-autoloads ещё более мощный инструмент; он обновляет автозагрузки для всех файлов в текущей директории.

Один и тот же магический комментарий может копировать любые формы в loaddefs.el. Форма, следующая за магическим комментарием, копируется дословно, кроме тех форм, которые обрабатываются механизмом автозагрузки особым образом (например, преобразованием в вызов autoload). Формы, которые не копируются дословно, следующие:

Определения для функции или функций-объектов:

defun и defmacro; также cl-defun и cl-defmacro (см. Список аргументов в Расширения Common Lisp), и define-overloadable-function (см. комментарий в mode-local.el).

Определения для основных или вспомогательных режимов:

define-minor-mode, define-globalized-minor-mode, define-generic-mode, define-derived-mode, easy-mmode-define-minor-mode, easy-mmode-define-global-mode, define-compilation-mode, и define-global-minor-mode.

Другие типы определений:

defcustom, defgroup, defclass (см. EIEIO в EIEIO), и define-skeleton (см. Автотипизация в Автотипизация).

Вы также можете использовать магический комментарий для выполнения формы во время сборки без её выполнения при загрузке самого файла. Для этого напишите форму в той же строке, что и магический комментарий. Поскольку она находится в комментарии, она ничего не делает при загрузке исходного файла; но M-x update-file-autoloads копирует её в loaddefs.el, где она выполняется во время сборки Emacs.

Следующий пример показывает, как doctor готовится к автозагрузке с помощью магического комментария:

;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))

Вот что это даёт в loaddefs.el:

(autoload 'doctor "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)

Обратный слэш и символ новой строки сразу после двойной кавычки являются соглашением, используемым только в предварительно загруженных нескомпилированных файлах Lisp, таких как loaddefs.el; они сообщают make-docfile поместить строку документации в файл etc/DOC. См. Сборка Emacs. См. также комментарии в lib-src/make-docfile.c. ‘(fn)’ в части использования строки документации заменяется именем функции при отображении различных функций справки (см. Функции справки).

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

;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)

Вы можете использовать строку, отличную от стандартной, как автозагрузочный cookie, и иметь соответствующие вызовы автозагрузки, записанные в файл, имя которого отличается от стандартного loaddefs.el. Emacs предоставляет две переменные для управления этим:

Переменная: generate-autoload-cookie

Значение этой переменной должно быть строкой, синтаксис которой представляет комментарий Lisp. M-x update-file-autoloads копирует форму Lisp, следующую за cookie, в файл автозагрузки, который она генерирует. Значение по умолчанию этой переменной — ";;;###autoload".

Переменная: generated-autoload-file

Значение этой переменной задаёт имя файла Emacs Lisp, в который должны быть записаны вызовы автозагрузки. Значение по умолчанию — loaddefs.el, но вы можете его переопределить, например, в разделе локальных переменных файла .el (см. Локальные переменные файла). Файл автозагрузки предполагается содержащим хвостовую часть, начинающуюся с символа подавления страницы.

Следующая функция может использоваться для явной загрузки библиотеки, указанной объектом автозагрузки:

Функция: autoload-do-load autoload &опционально имя только_макрос

Эта функция выполняет загрузку, указанную autoload, которая должна быть объектом автозагрузки. Необязательный аргумент имя, если он не nil, должен быть символом, значением функции которого является autoload; в этом случае, возвращаемое значение этой функции — новое значение функции символа. Если значение необязательного аргумента только_макрос равно macro, эта функция избегает загрузки функции, а только макроса.