Функциональности

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

Имя функциональности — это символ, обозначающий набор функций, переменных и т. д. Файл, в котором они определены, должен предоставлять эту функциональность. Другая программа, использующая их, может гарантировать наличие их определений, запросив эту функциональность. Если файл с определениями ещё не был загружен, это приведёт к его загрузке.

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

Например, определение для idlwave-complete-filename в idlwave.el содержит следующий код:

(defun idlwave-complete-filename ()
  "Use the comint stuff to complete a file name."
   (require 'comint)
   (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%={}\\-")
          (comint-completion-addsuffix nil)
          ...)
       (comint-dynamic-complete-filename)))

Выражение (require 'comint) загружает файл comint.el, если тот ещё не был загружен, гарантируя тем самым, что comint-dynamic-complete-filename определена. Обычно функциональности получают имена файлов, которые их предоставляют, поэтому указывать имя файла в require не требуется. (Обратите внимание, что оператор require важно размещать вне тела let. Загрузка библиотеки, пока её переменные связаны через let, может привести к непредвиденным последствиям: после завершения let переменные окажутся несвязанными.)

Файл comint.el содержит следующее выражение верхнего уровня:

(provide 'comint)

Это добавляет comint в глобальный список features, чтобы (require 'comint) впредь знала, что никаких действий предпринимать не нужно.

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

Хотя вызовы require верхнего уровня выполняются во время байтовой компиляции, вызовы provide — нет. Поэтому перед байтовой компиляцией можно гарантировать загрузку файла с определениями, добавив provide, за которым следует require для той же функциональности, как в следующем примере.

(provide 'my-feature)  ; Ignored by byte compiler,
                       ;   evaluated by load.
(require 'my-feature)  ; Evaluated by byte compiler.

Компилятор игнорирует provide, а затем обрабатывает require, загружая соответствующий файл. При загрузке файла выполняется вызов provide, поэтому последующий вызов require ничего не делает при загрузке файла.

Функция: provide feature &optional subfeatures

Эта функция объявляет, что feature теперь загружена или загружается в текущий сеанс Emacs. Это означает, что средства, связанные с feature, доступны или станут доступны другим программам на Lisp.

Непосредственное действие вызова provide — добавить feature в начало features, если её там ещё нет, и вызвать любой код eval-after-load, ожидающий её появления (см. раздел Перехватчики загрузки). Аргумент feature должен быть символом. provide возвращает feature.

Если указан аргумент subfeatures, он должен быть списком символов, обозначающих набор конкретных подфункциональностей, предоставляемых этой версией feature. Наличие подфункциональности можно проверить с помощью featurep. Подфункциональности полезны в тех случаях, когда пакет (то есть одна feature) достаточно сложен, чтобы было удобно давать имена различным его частям или возможностям, которые могут быть загружены или не загружены либо присутствовать или отсутствовать в конкретной версии. Пример см. в разделе Проверка доступности сетевых функций.

features
     ⇒ (bar bish)

(provide 'foo)
     ⇒ foo
features
     ⇒ (foo bar bish)

Если файл загружается для выполнения автозагрузки, но его загрузка прерывается из-за ошибки при вычислении содержимого, все определения функций и вызовы provide, выполненные во время загрузки, отменяются. См. раздел Автозагрузка.

Функция: require feature &optional filename noerror

Эта функция проверяет, присутствует ли feature в текущем сеансе Emacs (с помощью (featurep feature); см. ниже). Аргумент feature должен быть символом.

Если функциональность отсутствует, require загружает файл filename с помощью load. Если filename не указан, в качестве основы имени файла для загрузки используется имя символа feature. Однако в этом случае require требует, чтобы имя файла feature имело суффикс «.el» или «.elc» (возможно, дополненный суффиксом сжатия); файл, имя которого совпадает только с feature, использоваться не будет. (Переменная load-suffixes задаёт точные суффиксы Lisp, которые необходимо искать.)

Если noerror не равен nil, ошибки, возникшие непосредственно при загрузке файла, подавляются. В этом случае require возвращает nil, если загрузка файла завершается неудачей. Обычно require возвращает feature.

Если загрузка файла прошла успешно, но он не предоставил feature, require выдаёт ошибку об отсутствующей функциональности.

Функция: require-with-check feature &optional filename noerror

Эта функция работает так же, как require, за исключением случая, когда feature уже загружена (то есть уже входит в список в features; см. ниже). Если feature уже загружена, эта функция проверяет, была ли она предоставлена файлом, отличным от filename, и в таком случае по умолчанию выдаёт ошибку. Если значение необязательного аргумента noerror равно reload, функция не выдаёт ошибку, а принудительно перезагружает filename; если noerror имеет любое другое значение, не равное nil, функция выдаёт предупреждение о том, что feature уже предоставлена другим файлом.

Функция: featurep feature &optional subfeature

Эта функция возвращает t, если feature была предоставлена в текущем сеансе Emacs (то есть если feature входит в features). Если subfeature не равна nil, функция возвращает t, только если предоставлена и эта подфункциональность (то есть если subfeature входит в свойство subfeature символа feature).

Переменная: features

Значение этой переменной — список символов, обозначающих функциональности, загруженные в текущем сеансе Emacs. Каждый символ был добавлен в этот список вызовом provide. Порядок элементов в списке features не имеет значения.

Макрос use-package предоставляет удобный способ загрузить функциональность и настроить её для использования. Он позволяет совместить запрос функциональности, как это делает require, с кодом, который выполняется при фактической загрузке функциональности, подобно перехватчикам времени загрузки (см. раздел Перехватчики загрузки). Декларативный синтаксис use-package делает его особенно удобным для использования в пользовательских файлах инициализации.

Макрос: use-package feature &rest args

Этот макрос задаёт, как загружать указанную feature, а также как настраивать её и адаптировать для использования. Аргументы args представляют собой пары «ключ — значение». Вот некоторые важные ключи и их значения:

:init forms

Задаёт формы, которые следует выполнить до загрузки feature.

:config forms

Задаёт формы, которые следует выполнить после загрузки feature.

:defer condition

Если condition не равно nil, этот ключ указывает отложить загрузку feature до первого использования любой из автоматически загружаемых команд или переменных feature. Если condition — число n, он указывает загрузить feature после n секунд бездействия.

:commands commands…

Задаёт команды feature, которые следует загружать автоматически.

:bind keybindings…

Задаёт привязки клавиш для команд feature. Каждая привязка имеет следующий вид:

(key-sequence . command)

или

(:map keymap (key-sequence . command))

где key-sequence задаётся в формате, принимаемом макросом kbd (см. раздел Последовательности клавиш).

Подробнее о use-package см. в Руководстве пользователя use-package.