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

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

Макрос: 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 как способ изменения значения этого параметра при использовании интерфейса настройки. Функция setfunction должна принимать два аргумента: символ (имя параметра) и новое значение, и должна выполнять все необходимые действия для корректного обновления значения этого параметра (что может не означать простое присвоение параметра как переменной Lisp); предпочтительно, однако, она не должна разрушать свой аргумент value.

Если вы указываете это ключевое слово, строка документации переменной должна описывать, как выполнить ту же задачу в написанном вручную коде Lisp.

:get getfunction

Укажите getfunction как способ извлечения значения этого параметра. Функция getfunction должна принимать один аргумент — символ — и возвращать то, что Custom должен использовать в качестве текущего значения для этого символа (что не обязательно должно быть значением символа в Lisp).

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

:initialize function

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

custom-initialize-set

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

custom-initialize-default

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

custom-initialize-reset

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

custom-initialize-changed

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

custom-initialize-delay

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

:local value

Если value равно t, пометьте option как автоматически локальный для буфера; если значение равно permanent, также установите свойство option permanent-local в 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

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

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

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

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

Функция: custom-reevaluate-setting символ

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

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

Функция: custom-variable-p арг

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