Определение переменных настройки

Настраиваемые переменные, также называемые пользовательскими параметрами, — это глобальные переменные Lisp, значения которых можно задавать через интерфейс Customize. В отличие от других глобальных переменных, которые определяются с помощью defvar (см. раздел Определение глобальных переменных), настраиваемые переменные определяются с помощью макроса defcustom. Помимо вызова defvar в качестве подпрограммы, defcustom указывает, как переменная должна отображаться в интерфейсе Customize, какие значения ей разрешено принимать и т. д.

Макрос: defcustom option standard doc [keyword value]…

Этот макрос объявляет option пользовательским параметром (то есть настраиваемой переменной). Не заключайте option в кавычки.

Аргумент standard — это выражение, задающее стандартное значение для option. Вычисление формы defcustom вычисляет standard, но не обязательно связывает параметр с этим значением. Если у option уже есть значение по умолчанию, оно остается без изменений. Если пользователь уже сохранил настройку для option, настроенное пользователем значение устанавливается в качестве значения по умолчанию. В противном случае в качестве значения по умолчанию устанавливается результат вычисления standard.

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

Выражение standard может вычисляться и в разное другое время — каждый раз, когда механизму настройки требуется узнать стандартное значение option. Поэтому используйте выражение, вычисление которого безопасно в любое время.

Аргумент doc задает строку документации для переменной.

Если в defcustom не указана ни одна :group, будет использоваться последняя группа, определенная с помощью defgroup в том же файле. Таким образом, большинству defcustom не требуется явная :group.

Когда вы вычисляете форму defcustom с помощью C-M-x в режиме Emacs Lisp (eval-defun), специальная возможность eval-defun безусловно устанавливает переменную, не проверяя, является ли ее значение пустым. (Та же возможность применяется к defvar, см. раздел Определение глобальных переменных.) Использование eval-defun для уже определенного defcustom вызывает функцию :set (см. ниже), если она имеется.

Если поместить defcustom в предварительно загруженный файл Emacs Lisp (см. раздел Сборка Emacs), стандартное значение, установленное во время создания дампа, может оказаться неверным, например, если другая переменная, от которой оно зависит, еще не получила нужного значения. В этом случае используйте описанный ниже макрос custom-reevaluate-setting, чтобы повторно вычислить стандартное значение после запуска Emacs.

Помимо ключевых слов, перечисленных в разделе Общие ключевые слова элементов, этот макрос принимает следующие ключевые слова:

:type type

Используйте type в качестве типа данных для этого параметра. Он указывает, какие значения допустимы и как отображать значение (см. раздел Типы настройки). Для каждого defcustom следует указывать значение этого ключевого слова.

:options value-list

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

Это имеет смысл только для некоторых типов, включая на данный момент hook, plist и alist. Описание использования :options см. в определении соответствующего типа.

Повторное вычисление формы defcustom с другим значением :options не удаляет значения, добавленные при предыдущих вычислениях или вызовами custom-add-frequent-value (см. ниже).

:set setfunction

Укажите setfunction как функцию, которая изменяет значение этого параметра при использовании интерфейса Customize. Функция setfunction должна принимать два или три аргумента: символ (имя параметра), новое значение и необязательный индикатор buffer-local. Функция setfunction должна выполнять все необходимые действия для правильного обновления значения этого параметра (что не обязательно означает простую установку параметра как переменной Lisp); однако предпочтительно, чтобы она не изменяла свой аргумент-значение деструктивно. Если необязательный аргумент buffer-local не равен nil, новое значение следует установить локально для буфера, не затрагивая глобальное значение или значение по умолчанию. По умолчанию для setfunction используется set-default-toplevel-value.

Если setfunction определена, она также вызывается при вычислении формы defcustom с помощью C-M-x в режиме Emacs Lisp и при изменении значения option с помощью макроса setopt (см. setopt).

Если вы указываете это ключевое слово, в строке документации переменной следует описать, как выполнить ту же задачу в написанном вручную коде Lisp: напрямую вызвав setfunction или воспользовавшись setopt либо setopt-local.

:get getfunction

Укажите getfunction как функцию, извлекающую значение этого параметра. Функция getfunction должна принимать один аргумент — символ — и возвращать значение, которое Customize следует использовать как текущее значение этого символа (оно не обязано совпадать со значением символа в Lisp). По умолчанию используется default-toplevel-value.

Чтобы правильно использовать :get, необходимо хорошо понимать работу Custom. Этот параметр предназначен для значений, которые в Custom рассматриваются как переменные, но фактически не хранятся в переменных Lisp. Указание getfunction для значения, которое действительно хранится в переменной Lisp, почти наверняка является ошибкой.

:initialize function

function должна быть функцией, используемой для инициализации переменной при вычислении defcustom. Она должна принимать два аргумента: имя параметра (символ) и значение. Ниже приведены некоторые заранее определенные функции, предназначенные для такого использования:

custom-initialize-set

Используйте функцию :set переменной для ее инициализации, но не выполняйте повторную инициализацию, если переменная уже не пуста.

custom-initialize-default

Подобно custom-initialize-set, но для установки переменной используйте функцию set-default-toplevel-value вместо функции :set переменной. Обычно этот вариант выбирают для переменной, функция :set которой включает или выключает второстепенный режим; при таком выборе определение переменной не вызывает функцию второстепенного режима, а настройка переменной вызывает.

custom-initialize-reset

Всегда используйте функцию :set для инициализации переменной. Если переменная уже не пуста, сбросьте ее, вызвав функцию :set с текущим значением (возвращаемым методом :get). Это функция :initialize по умолчанию.

custom-initialize-changed

Используйте функцию :set для инициализации переменной, если она уже установлена или была настроена; в противном случае просто используйте set-default-toplevel-value.

custom-initialize-after-file-load

Эта функция ведет себя как custom-initialize-set, но откладывает фактическую инициализацию до загрузки содержащего ее файла. Это может быть полезно для устранения распространенной зависимости, когда функция установки (или используемая ею функция) должна быть определена после переменной, например, если для глобального второстепенного режима указана nil :init-value.

custom-initialize-delay

Эта функция ведет себя как custom-initialize-set, но откладывает фактическую инициализацию до следующего запуска Emacs. Ее следует использовать в предварительно загружаемых файлах Lisp (загружаемых при сборке Emacs), если важно обеспечить выполнение инициализации в контексте времени выполнения (который может отличаться системой или программной средой). См. раздел custom-initialize-delay.

:local value

Если value равно t, пометьте option как автоматически локальную для буфера; если значение равно permanent, также установите свойство permanent-local переменной option в t. Наконец, если значение равно permanent-only, установите свойство permanent-local переменной option в t, не помечая ее как автоматически локальную для буфера. См. раздел Создание и удаление привязок, локальных для буфера.

:risky value

Установите свойство risky-local-variable переменной в значение value (см. раздел Локальные переменные файлов).

:safe function

Установите свойство safe-local-variable переменной в значение function (см. раздел Локальные переменные файлов).

:set-after variables

При установке переменных согласно сохраненным настройкам сначала установите переменные variables, а затем эту переменную; то есть отложите установку этой переменной до обработки остальных. Используйте :set-after, если установка этой переменной не будет работать правильно, пока другие переменные не получат предназначенные для них значения.

Полезно указывать ключевое слово :require для параметра, включающего определенную возможность. Благодаря этому Emacs загружает возможность, если она еще не загружена, при каждой установке параметра. См. раздел Общие ключевые слова элементов. Например:

(defcustom frobnicate-automatically nil
  "Non-nil means automatically frobnicate all buffers."
  :type 'boolean
  :require 'frobnicate-mode
  :group 'frobnicate)

Если тип элемента настройки, например hook или alist, поддерживает :options, можно добавлять значения в список извне объявления defcustom, вызывая custom-add-frequent-value. Например, если вы определили функцию my-lisp-mode-initialization, предназначенную для вызова из emacs-lisp-mode-hook, возможно, вы захотите добавить ее в список подходящих значений для emacs-lisp-mode-hook, не редактируя ее определение. Это можно сделать так:

(custom-add-frequent-value 'emacs-lisp-mode-hook
   'my-lisp-mode-initialization)

Функция: custom-add-frequent-value symbol value

Добавляет value в список подходящих значений для параметра настройки symbol.

Точный эффект добавления значения зависит от типа настройки symbol.

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

Внутри defcustom использует свойство символа standard-value для записи выражения стандартного значения, saved-value — для записи значения, сохраненного пользователем с помощью буфера настройки, а customized-value — для записи значения, заданного пользователем в буфере настройки, но не сохраненного. См. раздел Свойства символов. Кроме того, существует свойство themed-value, используемое для записи значения, заданного темой (см. раздел Пользовательские темы). Эти свойства представляют собой списки, car которых является выражением, вычисляемым в это значение.

Функция: custom-reevaluate-setting symbol

Эта функция повторно вычисляет стандартное значение symbol, который должен быть пользовательским параметром, объявленным с помощью defcustom. Если переменная была настроена, функция вместо этого повторно вычисляет сохраненное значение. Затем она устанавливает пользовательский параметр в это значение (используя свойство :set параметра, если оно определено).

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

Функция: custom-variable-p arg

Эта функция возвращает значение, отличное от nil, если arg является настраиваемой переменной. Настраиваемая переменная — это либо переменная со свойством standard-value или custom-autoload (обычно это означает, что она объявлена с помощью defcustom), либо псевдоним другой настраиваемой переменной.