Переменные настройки, также называемые пользовательскими опциями, — это глобальные переменные Lisp, значения которых могут быть установлены через интерфейс Customize. В отличие от других глобальных переменных, которые определяются с помощью
defvar (см. Определение глобальных переменных), переменные настройки определяются с помощью макроса defcustom. В дополнение к вызову
defvar в качестве подпрограммы, defcustom указывает, как переменная должна отображаться в интерфейсе Customize, какие значения ей разрешено принимать и т. д.
Этот макрос объявляет 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 должна принимать два аргумента: символ (имя опции) и новое значение, и должна сделать все необходимое для правильного обновления значения для этой опции (что может не означать простое присвоение опции как переменной Lisp); предпочтительно, однако, она не должна изменять ее аргумент значения деструктивно. Значение по умолчанию для setfunction — set-default-toplevel-value.
Если определена, setfunction также будет вызвана при выполнении формы defcustom с C-M-x в режиме Emacs Lisp, а также когда значение option изменяется с помощью макроса setopt (см. setopt).
Если вы указываете это ключевое слово, строковое описание переменной должно описывать, как выполнить ту же работу в написанном вручную коде Lisp, либо вызвав setfunction напрямую, либо используя setopt.
:get getfunction ¶Укажите getfunction как способ извлечения значения этой опции. Функция getfunction должна принимать один аргумент — символ — и возвращать все, что customize должен использовать в качестве текущего значения для этого символа (это не обязательно значение Lisp для символа). Значение по умолчанию — default-toplevel-value.
Вы должны по-настоящему понять принципы работы Custom, чтобы правильно использовать :get. Он предназначен для значений, которые в 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-delayЭта функция ведет себя как custom-initialize-set, но откладывает фактическую инициализацию до следующего запуска Emacs. Это следует использовать в предварительно загружаемых файлах (или для автозагружаемых переменных), чтобы инициализация выполнялась в контексте времени выполнения, а не в контексте времени сборки. Это также имеет побочный эффект, что (отложенная) инициализация выполняется с использованием функции :set. См. Сборка Emacs.
:local value ¶Если value равно t, помечайте option как автоматически локальную для буфера; если значение равно permanent, также установите свойство 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 "Не-nil означает автоматическое frobnicate всех буферов." :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)
Для опции настройки symbol добавьте value в список разумных значений.
Точный эффект добавления значения зависит от типа настройки symbol.
Поскольку вычисление формы defcustom не очищает ранее добавленные значения, программы Lisp могут использовать эту функцию для добавления значений для опций, которые еще не определены.
Внутренне defcustom использует свойство символа standard-value для записи выражения для стандартного значения, saved-value для записи значения, сохраненного пользователем в буфере настройки, и customized-value для записи значения, установленного пользователем в буфере настройки, но не сохраненного. См. Свойства символов. Кроме того, есть themed-value, который используется для записи значения, установленного темой (см. Темы настройки). Эти свойства являются списками, первым элементом которых является выражение, вычисляемое в значение.
Эта функция повторно вычисляет стандартное значение symbol, которое должно быть опцией пользователя, объявленной с помощью defcustom. Если переменная была настроена, эта функция повторно вычисляет сохраненное значение вместо этого. Затем она устанавливает опцию пользователя в это значение (используя свойство :set опции, если оно определено).
Это полезно для настраиваемых опций, которые определены до того, как их значение могло быть правильно вычислено. Например, во время запуска Emacs вызывает эту функцию для некоторых опций пользователя, которые были определены в предварительно загружаемых файлах Emacs Lisp, но чьи начальные значения зависят от информации, доступной только во время выполнения.
Эта функция возвращает не-nil, если arg является настраиваемой переменной. Настраиваемая переменная — это либо переменная, имеющая свойство standard-value или custom-autoload (обычно означает, что она была объявлена с помощью defcustom), либо псевдоним другой настраиваемой переменной.