Средство автозагрузки позволяет зарегистрировать существование функции или макроса, но отложить загрузку файла, который их определяет. Первый вызов функции автоматически загружает нужную библиотеку, чтобы установить настоящее определение и другой связанный код, а затем выполняет настоящее определение так, как если бы оно было загружено с самого начала. Автозагрузка также может быть инициирована поиском документации функции или макроса (см. Основы документации) и дополнением имен переменных и функций (см. Автозагрузка по префиксу ниже).
Существует два способа настройки автозагружаемой функции: вызов autoload и запись «волшебного» комментария в исходном коде перед настоящим определением. autoload — это низкоуровневый примитив для автозагрузки; любая программа на Lisp может вызывать autoload в любое время. Волшебные комментарии — это самый удобный способ сделать функцию автозагружаемой для пакетов, устанавливаемых вместе с Emacs. Эти комментарии сами по себе ничего не делают, но служат руководством для команды loaddefs-generate, которая создаёт вызовы autoload и организует их выполнение при сборке Emacs.
Эта функция определяет функцию (или макрос) с именем function так, чтобы она автоматически загружалась из filename. Строка filename указывает файл, который нужно загрузить для получения настоящего определения function.
Если filename не содержит ни имени каталога, ни суффикса .el или .elc, эта функция настаивает на добавлении одного из этих суффиксов и не будет загружать файл, имя которого состоит только из filename без добавленного суффикса. (Переменная load-suffixes задаёт точные требуемые суффиксы.)
Аргумент docstring — это строка документации для функции. Указание строки документации в вызове autoload позволяет просматривать документацию без загрузки настоящего определения функции. Обычно она должна быть идентична строке документации в самом определении функции. Если это не так, то строка документации из определения функции вступает в силу после её загрузки.
Если interactive не равен nil, это означает, что function можно вызывать интерактивно. Это позволяет дополнению в M-x работать без загрузки настоящего определения function. Полная интерактивная спецификация здесь не приводится; она не нужна, пока пользователь действительно не вызовет function, а когда это произойдёт, настанет время загрузить настоящее определение.
Если interactive является списком, он интерпретируется как список режимов, для которых применима эта команда.
Вы можете автозагружать макросы и клавиатурные карты, а также обычные функции. Укажите type как macro, если function на самом деле является макросом. Укажите type как keymap, если function на самом деле является клавиатурной картой. Различным частям Emacs необходимо знать эту информацию без загрузки настоящего определения.
Автозагружаемая клавиатурная карта загружается автоматически во время поиска клавиш, когда связывание префиксной клавиши является символом function. Автозагрузка не происходит для других видов доступа к клавиатурной карте. В частности, она не происходит, когда программа на Lisp получает клавиатурную карту из значения переменной и вызывает keymap-set; даже если имя переменной — тот же символ function.
Если function уже имеет непустое определение функции, не являющееся объектом автозагрузки, эта функция ничего не делает и возвращает nil. В противном случае она создаёт объект автозагрузки (см. Тип автозагрузки) и сохраняет его как определение функции для function. Объект автозагрузки имеет следующий вид:
(autoload filename docstring interactive type)
Например,
(symbol-function 'run-prolog)
⇒ (autoload "prolog" 169681 t nil)
В этом случае "prolog" — это имя файла для загрузки, 169681 ссылается на строку документации в файле emacs/etc/DOC (см. Основы документации), t означает, что функция интерактивна, а nil — что это не макрос и не клавиатурная карта.
Эта функция возвращает не nil, если object является объектом автозагрузки. Например, чтобы проверить, определён ли run-prolog как автозагружаемая функция, вычислите
(autoloadp (symbol-function 'run-prolog))
Автозагружаемый файл обычно содержит другие определения и может требовать или предоставлять одну или несколько возможностей. Если файл загружен не полностью (из-за ошибки при вычислении его содержимого), любые определения функций или вызовы provide, произошедшие во время загрузки, отменяются. Это сделано для того, чтобы следующая попытка вызвать любую функцию, автозагружаемую из этого файла, снова попыталась загрузить файл. Если бы этого не было, то некоторые функции в файле могли бы быть определены прерванной загрузкой, но не работать должным образом из-за отсутствия некоторых подпрограмм, которые не были загружены успешно, поскольку они идут позже в файле.
Если автозагружаемый файл не определяет нужную функцию или макрос Lisp, то возникает ошибка с данными "Autoloading failed to define function function-name".
Волшебный комментарий автозагрузки (часто называемый печеньем автозагрузки) состоит из ‘;;;###autoload’, расположенного на отдельной строке, непосредственно перед настоящим определением функции в её файле исходного кода, допускающем автозагрузку. Функция loaddefs-generate записывает соответствующий вызов autoload в loaddefs.el. (Строка, служащая печеньем автозагрузки, и имя файла, генерируемого loaddefs-generate, могут быть изменены относительно указанных выше значений по умолчанию; см. ниже.) Сборка Emacs загружает loaddefs.el и, таким образом, вызывает autoload.
Тот же волшебный комментарий может копировать любые формы в 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, define-compilation-mode и define-global-minor-mode.
defcustom, defgroup, deftheme, defclass (см. EIEIO в EIEIO) и define-skeleton (см. Автотипизация в Автотипизации).
Вы также можете использовать волшебный комментарий для выполнения формы во время сборки без её выполнения при загрузке самого файла. Для этого запишите форму на той же строке, что и волшебный комментарий. Поскольку она находится в комментарии, она ничего не делает при загрузке исходного файла; но loaddefs-generate копирует её в loaddefs.el, где она выполняется во время сборки Emacs.
Следующий пример показывает, как doctor подготавливается к автозагрузке с помощью волшебного комментария:
;;;###autoload (defun doctor () "Переключиться в буфер *doctor* и начать психотерапию." (interactive) (switch-to-buffer "*doctor*") (doctor-mode))
Вот что создаётся в loaddefs.el:
(autoload 'doctor "doctor" "\ Переключиться в буфер *doctor* и начать психотерапию. \(fn)" t nil)
Хотя loaddefs.el не предназначен для редактирования, мы стараемся сохранять его в некоторой степени читаемым для людей. Например, управляющие символы в значениях defvar экранируются, и мы вставляем обратную косую черту и новую строку сразу после двойной кавычки строки документации, чтобы уменьшить длину строки. ‘(fn)’ в части использования строки документации заменяется на имя функции при отображении различными функциями помощи (см. Функции помощи).
Если вы пишете определение функции с необычным макросом, который не является одним из известных и распознаваемых методов определения функций, использование обычного волшебного комментария автозагрузки привело бы к копированию всего определения в loaddefs.el. Это нежелательно. Вы можете поместить нужный вызов autoload в loaddefs.el вместо этого, написав так:
;;;###autoload (autoload 'foo "myfile") (mydefunmacro foo ...)
Вы можете использовать нестандартную строку в качестве печенья автозагрузки и записывать соответствующие вызовы автозагрузки в файл с именем, отличным от стандартного loaddefs.el. Emacs предоставляет две переменные для управления этим:
Значение этой константы — регулярное выражение, которое соответствует печеньям автозагрузки. loaddefs-generate копирует форму Lisp, следующую за печеньем, в создаваемый файл автозагрузки. Оно будет соответствовать комментариям типа ‘;;;###autoload’ и ‘;;;###calc-autoload’.
Значение этой переменной задаёт файл Emacs Lisp, в который должны помещаться вызовы автозагрузки. Значение по умолчанию — loaddefs.el, но вы можете переопределить его, например, в разделе локальных переменных файла .el (см. Локальные переменные файла). Предполагается, что файл автозагрузки содержит трейлер, начинающийся с символа подачи страницы.
Следующая функция может использоваться для явной загрузки библиотеки, указанной объектом автозагрузки:
Эта функция выполняет загрузку, заданную autoload, который должен быть объектом автозагрузки. Необязательный аргумент name, если он не равен nil, должен быть символом, значение функции которого равно autoload; в этом случае возвращаемым значением этой функции будет новое значение функции символа. Если значение необязательного аргумента macro-only равно macro, эта функция избегает загрузки функции, загружая только макрос.