Локальные переменные каталога

Для каталога можно задать значения локальных переменных, общие для всех файлов в этом каталоге; Emacs использует их, чтобы создавать привязки этих переменных, локальные для буфера, в буферах, посещающих любой файл в этом каталоге. Это полезно, когда файлы в каталоге принадлежат одному проекту и поэтому используют одни и те же локальные переменные.

Задать локальные переменные каталога можно двумя способами: поместив их в специальный файл или определив для этого каталога класс проекта.

Константа: dir-locals-file

Эта константа содержит имя файла, в котором Emacs ищет локальные переменные каталога. Имя файла — .dir-locals.el. Наличие файла с таким именем в каталоге заставляет Emacs применять его настройки ко всем файлам в этом каталоге и его подкаталогах (при желании подкаталоги можно исключить; см. ниже). Если у некоторых подкаталогов есть собственные файлы .dir-locals.el, Emacs использует настройки из самого глубокого файла, найденного при движении вверх по дереву каталогов, начиная с каталога файла. Эта константа также используется для получения имени второго файла dir-locals — .dir-locals-2.el. Если этот второй файл dir-locals находится в том же каталоге, что и .dir-locals.el, он загружается в дополнение к .dir-locals.el. Это полезно, когда .dir-locals.el находится под контролем версий в общем репозитории и не может использоваться для персональных настроек. Файл задаёт локальные переменные в виде списка специального формата; подробности см. в разделе Локальные переменные для каждого каталога в Руководстве GNU Emacs.

Функция: hack-dir-local-variables

Эта функция читает файл .dir-locals.el и сохраняет локальные переменные каталога в file-local-variables-alist, локальном для буфера, посещающего любой файл в этом каталоге, не применяя их. Она также сохраняет настройки каталога в dir-locals-class-alist, где определяет специальный класс для каталога, в котором был найден файл .dir-locals.el. Эта функция работает, вызывая dir-locals-set-class-variables и dir-locals-set-directory-class, описанные ниже.

Функция: hack-dir-local-variables-non-file-buffer

Эта функция ищет локальные переменные каталога и сразу применяет их в текущем буфере. Предполагается, что её будут вызывать команды режимов для буферов, не связанных с файлами, например буферов Dired, чтобы такие буферы учитывали настройки локальных переменных каталога. Для буферов, не связанных с файлами, Emacs ищет локальные переменные каталога в default-directory и его родительских каталогах.

Функция: dir-locals-set-class-variables class variables

Эта функция задаёт набор настроек переменных для класса с именем class, который является символом. Позже можно назначить этот класс одному или нескольким каталогам, и Emacs будет применять эти настройки переменных ко всем файлам в этих каталогах. Список в variables может иметь одну из двух форм: (major-mode . alist) или (directory . list). В первом случае, если в буфере файла включён режим, производный от major-mode, применяются все переменные из связанного alist; alist должен иметь форму (name . value). Специальное значение nil для major-mode означает, что настройки применимы к любому режиму. В alist можно использовать специальное name: subdirs. Если связанное значение равно nil, alist применяется только к файлам в соответствующем каталоге, но не к файлам в его подкаталогах.

Во втором случае для variables, если directory является начальной подстрокой каталога файла, list применяется рекурсивно согласно приведённым выше правилам; list должен иметь одну из двух форм, принимаемых этой функцией для variables.

Функция: dir-locals-set-directory-class directory class &optional mtime

Эта функция назначает class всем файлам в directory и его подкаталогах. После этого все настройки переменных, заданные для class, будут применяться к любому посещаемому файлу в directory и его подкаталогах. Класс class должен быть предварительно определён с помощью dir-locals-set-class-variables.

Emacs использует эту функцию внутри программы при загрузке переменных каталога из файла .dir-locals.el. В этом случае необязательный аргумент mtime содержит время изменения файла (возвращаемое file-attributes). Emacs использует это время, чтобы проверять, остаются ли сохранённые локальные переменные актуальными. Если вы назначаете класс напрямую, а не через файл, этот аргумент должен быть равен nil.

Переменная: dir-locals-class-alist

Этот alist содержит символы классов и связанные с ними настройки переменных. Он обновляется функцией dir-locals-set-class-variables.

Переменная: dir-locals-directory-cache

Этот alist содержит имена каталогов, назначенные им имена классов и время изменения связанного файла локальных переменных каталога (если он есть). Функция dir-locals-set-directory-class обновляет этот список.

Переменная: dir-local-variables-alist

Эта локальная для буфера переменная содержит alist настроек локальных переменных каталога. Каждый элемент alist имеет форму (var . value), где var — символ локальной переменной, а value — её значение (такая же структура используется в file-local-variables-alist; см. Локальные переменные файла). При посещении файла Emacs собирает все локальные переменные каталога в этот alist, а затем функция hack-local-variables применяет их одну за другой (см. также Локальные переменные файла).

Переменная: hack-dir-local-get-variables-functions

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

Функции этого хука вызываются без аргументов в буфере, к которому предполагается применить локальные переменные каталога, после выполнения функции основного режима буфера, поэтому они могут использовать такие источники информации, как major-mode или buffer-file-name, чтобы найти переменные, которые следует применить.

Функция должна возвращать либо cons-ячейку формы (directory . alist), либо список таких cons-ячеек. Возвращаемое значение nil означает, что локальные переменные каталога не найдены. directory должна быть строкой — именем каталога, к которому относятся переменные. alist — это список переменных и их значений, применимых к текущему буферу; каждый его элемент имеет форму (varname . value).

Различные значения alist, возвращаемые этими функциями, будут объединены; в случае конфликтов настройки из более глубоких каталогов имеют приоритет над настройками из каталогов, расположенных выше в иерархии. Поскольку этот хук выполняется при каждом посещении файла, важно, чтобы эти функции работали эффективно; для этого обычно требуется какое-либо кэширование.

Переменная: enable-dir-local-variables

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