File Local Variables — Elisp

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

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

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

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

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

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

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

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

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

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

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

Эта функция работает, перебирая список, хранящийся в file-local-variables-alist, и применяя каждую локальную переменную поочередно. Она вызывает before-hack-local-variables-hook и hack-local-variables-hook перед и после применения переменных соответственно. Она вызывает переднюю функцию только если список не 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 для переменных, определённых в исходном коде C, добавьте имена и свойства этих переменных в список в разделе «Безопасные локальные переменные» в files.el.

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

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

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

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

Эта переменная предоставляет другой способ отметить некоторые значения переменных как безопасные. Это список списков (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 непосредственно.

Любая переменная, имя которой имеет свойство non-nil risky-local-variable, считается рискованной. При определении пользовательского параметра с помощью 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 (всегда безопасно при условии, что аргументы являются константами).

END_OF_DOCUMENT_MARKER

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