File Local Variables — Elisp

Локальные переменные файла

Файл может задавать значения локальных переменных; Emacs использует их для создания локальных для буфера привязок этих переменных в буфере, посещающем этот файл. Основные сведения о локальных переменных файлов см. в разделе Локальные переменные в файлах руководства Руководство GNU Emacs. В этом разделе описываются функции и переменные, влияющие на обработку локальных переменных файлов.

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

Для дополнительной безопасности при чтении локальных переменных файлов Emacs временно привязывает read-circle к nil (см. Функции ввода). Это не позволяет считывателю Lisp распознавать циклические и совместно используемые структуры Lisp (см. Синтаксис чтения циклических объектов).

Параметр пользователя: enable-local-variables

Эта переменная управляет обработкой локальных переменных файлов. Возможные значения:

t (значение по умолчанию): Устанавливать безопасные переменные и (один раз) запрашивать разрешение на установку небезопасных переменных.
:safe: Устанавливать только безопасные переменные и не задавать вопросов.
:all: Устанавливать все переменные и не задавать вопросов.
nil: Не устанавливать никакие переменные.
любое другое значение: (Один раз) запрашивать разрешение на установку всех переменных.

Переменная: inhibit-local-variables-regexps: Это список регулярных выражений. Если имя файла соответствует элементу этого списка, файл не проверяется на наличие каких-либо видов локальных переменных. Примеры причин, по которым может понадобиться использовать эту переменную, см. в разделе Как Emacs выбирает основной режим.

Переменная: permanently-enabled-local-variables: По умолчанию некоторые настройки локальных переменных учитываются, даже если enable-local-variables имеет значение nil. По умолчанию это относится только к настройке локальной переменной lexical-binding, но управлять этим можно с помощью данной переменной, представляющей собой список символов.

Переменная: safe-local-variable-directories: Это список каталогов, в которых локальные переменные всегда разрешены. Локальные переменные каталогов, загруженные из этих каталогов, например переменные из .dir-locals.el, будут разрешены, даже если они небезопасны. Каталоги в этом списке должны быть абсолютными именами файлов с полностью раскрытыми путями. Они также могут быть удалёнными каталогами, если переменная enable-remote-dir-locals имеет значение, отличное от nil.

Функция: hack-local-variables &optional handle-mode

Эта функция разбирает любые локальные переменные, заданные содержимым текущего буфера, и связывает или вычисляет их соответствующим образом. Здесь учитывается переменная enable-local-variables. Однако эта функция не ищет локальную переменную ‘mode:’ в строке ‘-*-’. Это делает set-auto-mode, также учитывая enable-local-variables (см. Как Emacs выбирает основной режим).

Эта функция также применяет локальные переменные каталогов, заданные в .dir-locals.el. Если буфер не посещает какой-либо файл, применяются те локальные переменные каталогов, которые действовали бы для файлов в default-directory (см. Локальные переменные каталогов).

Эта функция проходит по спискам ассоциаций, хранящимся в file-local-variables-alist и dir-local-variables-alist, и по очереди применяет каждую локальную переменную. До и после применения переменных она соответственно вызывает before-hack-local-variables-hook и hack-local-variables-hook. Она вызывает предшествующий хук только если file-local-variables-alist имеет значение, отличное от nil; другой хук вызывается всегда. Эта функция игнорирует элемент ‘mode’, если он указывает тот же основной режим, который уже установлен для буфера.

Если необязательный аргумент handle-mode равен t, функция только возвращает символ, указывающий основной режим, если он задан в строке ‘-*-’ или в списке локальных переменных, и nil в противном случае. Она не устанавливает режим или какие-либо другие локальные переменные файла. Если handle-mode имеет значение, отличное от nil или t, все настройки ‘mode’ в строке ‘-*-’ или в списке локальных переменных игнорируются, а остальные настройки применяются. Если handle-mode равен nil, устанавливаются все локальные переменные файла.

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

Переменная: before-hack-local-variables-hook: Emacs вызывает этот хук непосредственно перед применением локальных переменных файла, хранящихся в file-local-variables-alist.

Переменная: hack-local-variables-hook: Emacs вызывает этот хук сразу после завершения применения локальных переменных файла, хранящихся в file-local-variables-alist.

Безопасные значения переменной можно задавать с помощью свойства safe-local-variable. Значением этого свойства должна быть функция с одним аргументом; любое значение считается безопасным, если функция возвращает не-nil для этого значения. Многие часто встречающиеся файловые переменные имеют свойства safe-local-variable; среди них fill-column, fill-prefix и indent-tabs-mode. Для безопасных переменных с булевыми значениями используйте booleanp в качестве значения свойства.

Поскольку значение safe-local-variable проверяется при загрузке файлов, функция должна быть эффективной и в идеале не должна приводить к загрузке библиотек для определения безопасности (например, она не должна быть функцией автозагрузки).

Чтобы определить свойства safe-local-variable для переменных, определённых в исходном коде на C, добавьте имена этих переменных и их свойства в список раздела «Safe local variables» файла files.el.

При определении пользовательского параметра с помощью defcustom можно задать его свойство safe-local-variable, добавив аргументы :safe function в defcustom (см. Определение переменных настройки). Однако предикат безопасности, определённый с помощью :safe, станет известен только после загрузки пакета, содержащего defcustom, что часто происходит слишком поздно. В качестве альтернативы можно использовать cookie автозагрузки (см. Автозагрузка), чтобы назначить параметру предикат безопасности, например так:

;;;###autoload (put 'var 'safe-local-variable 'pred)

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

Параметр пользователя: safe-local-variable-values

Эта переменная предоставляет ещё один способ пометить некоторые значения переменных как безопасные. Это список пар cons (var . val), где var — имя переменной, а val — безопасное для этой переменной значение.

Когда Emacs спрашивает пользователя, следует ли выполнять набор спецификаций локальных переменных файла, пользователь может выбрать, чтобы они считались безопасными. В этом случае соответствующие пары переменная/значение добавляются в safe-local-variable-values и сохраняются в пользовательском файле настройки.

Параметр пользователя: ignored-local-variable-values: Если некоторые значения определённых локальных переменных нужно всегда полностью игнорировать, можно использовать эту переменную. Её значение имеет ту же форму, что и safe-local-variable-values; настройка локальной переменной файла со значением, включённым в список, всегда будет игнорироваться при обработке локальных переменных, заданных файлом. Как и в случае с этой переменной, когда Emacs спрашивает пользователя, следует ли выполнять локальные переменные файла, пользователь может выбрать, чтобы определённые значения игнорировались постоянно; тогда эта переменная изменится и сохранится в пользовательском файле настройки. Пары переменная/значение, указанные в этой переменной, имеют приоритет над такими же парами в safe-local-variable-values.

Функция: safe-local-variable-p sym val: Эта функция возвращает не-nil, если согласно приведённым выше критериям безопасно присвоить sym значение val.

Некоторые переменные считаются рискованными. Если переменная рискованная, она никогда не добавляется автоматически в safe-local-variable-values; перед её установкой Emacs всегда запрашивает подтверждение, если только пользователь явно не разрешит значение, изменив непосредственно safe-local-variable-values.

Любая переменная, у имени которой есть свойство risky-local-variable, отличное от nil, считается рискованной. При определении пользовательского параметра с помощью defcustom можно задать его свойство risky-local-variable, добавив аргументы :risky value в defcustom (см. Определение переменных настройки). Кроме того, любая переменная, имя которой оканчивается на ‘-command’, ‘-frame-alist’, ‘-function’, ‘-functions’, ‘-hook’, ‘-hooks’, ‘-form’, ‘-forms’, ‘-map’, ‘-map-alist’, ‘-mode-alist’, ‘-program’ или ‘-predicate’, автоматически считается рискованной. Рискованными также считаются переменные ‘font-lock-keywords’, ‘font-lock-keywords’ с последующей цифрой и ‘font-lock-syntactic-keywords’.

Функция: risky-local-variable-p sym: Эта функция возвращает не-nil, если согласно приведённым выше критериям sym является рискованной переменной.

Переменная: ignored-local-variables: Эта переменная содержит список переменных, которым файлы не должны задавать локальные значения. Любое значение, указанное для одной из этих переменных, полностью игнорируется.

«Переменная» ‘Eval:’ также может служить лазейкой, поэтому обычно Emacs запрашивает подтверждение перед её обработкой.

Параметр пользователя: enable-local-eval: Эта переменная управляет обработкой ‘Eval:’ в строках ‘-*-’ или списках локальных переменных посещаемых файлов. Значение t означает обрабатывать их безусловно; nil — игнорировать их; любое другое значение означает спрашивать пользователя, что делать с каждым файлом. Значение по умолчанию — maybe.

Параметр пользователя: safe-local-eval-forms: Эта переменная содержит список выражений, которые безопасно вычислять, если они обнаружены в «переменной» ‘Eval:’ в списке локальных переменных файла.

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

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