Определение второстепенных режимов

Макрос define-minor-mode предоставляет удобный способ реализации режима в одном самодостаточном определении.

Макрос: define-minor-mode mode doc keyword-args… body…

Этот макрос определяет новый второстепенный режим с именем mode (символ). Он определяет команду с именем mode для переключения второстепенного режима, с doc в качестве её строки документации.

Команда переключения принимает один необязательный (префиксный) аргумент. Если она вызывается интерактивно без аргумента, она включает или выключает режим. Положительный префиксный аргумент включает режим, любой другой префиксный аргумент выключает его. Из Lisp, аргумент toggle переключает режим, а пропущенный или nil аргумент включает режим. Это упрощает включение второстепенного режима в крючке основного режима, например. Если doc равно nil, макрос предоставляет строку документации по умолчанию, объясняющую вышесказанное.

По умолчанию он также определяет переменную с именем mode, которая устанавливается в t или nil при включении или выключении режима.

Аргументы keyword-args состоят из ключевых слов, после которых следуют соответствующие значения. Некоторые ключевые слова имеют специальное значение:

:global global

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

Одним из эффектов превращения второстепенного режима в глобальный является то, что переменная mode становится переменной настройки. Переключение её через интерфейс Настройка включает и выключает режим, а её значение может быть сохранено для будущих сессий Emacs (см. Сохранение настроек в Справочнике по GNU Emacs. Для работы сохранённой переменной необходимо убедиться, что функция второстепенного режима доступна каждый раз при запуске Emacs; обычно это делается путём обозначения формы define-minor-mode как загружаемой автоматически.

:init-value init-value

Это значение, в которое инициализируется переменная mode. За исключением необычных случаев (см. ниже), это значение должно быть nil.

:lighter lighter

Строка lighter указывает, что отображать в строке режима, когда режим включен; если она nil, режим не отображается в строке режима.

:keymap keymap

Необязательный аргумент keymap задаёт ключевую карту для второстепенного режима. Если не nil, это должно быть имя переменной (значение которой является ключевой картой), ключевая карта или список пар вида

(key-sequence . definition)

где каждая key-sequence и definition являются аргументами, подходящими для передачи в define-key (см. Изменение назначений клавиш). Если keymap является ключевой картой или списком пар, это также определяет переменную mode-map.

:variable place

Это заменяет переменную по умолчанию mode, используемую для хранения состояния режима. Если вы это укажете, переменная mode не определяется, а любой аргумент init-value игнорируется. place может быть другой именованной переменной (которую вы должны определить сами), или любым элементом, который может быть использован с функцией setf (см. Обобщенные переменные). place также может быть списком (get . set), где get — выражение, возвращающее текущее состояние, а set — функция от одного аргумента (состояния), которая должна быть присвоена place.

:after-hook after-hook

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

:interactive value

Второстепенные режимы по умолчанию являются интерактивными командами. Если value равно nil, это запрещается. Если value является списком символов, используется для указания, в каких основных режимах этот второстепенный режим полезен.

Любые другие ключевые аргументы передаются напрямую в defcustom генерируемые для переменной mode.

Команда с именем mode сначала выполняет стандартные действия, такие как установка переменной с именем mode, а затем выполняет формы body, если они есть. Затем она выполняет переменную крючка режима mode-hook и завершает выполнением любой формы в :after-hook. (Обратите внимание, что всё это, включая выполнение крючка, выполняется как при включении, так и при выключении режима.)

Начальное значение должно быть nil за исключением случаев, когда (1) режим предварительно загружен в Emacs или (2) нет проблем с загрузкой для включения режима, даже если пользователь этого не запросил. Например, если режим не оказывает никакого влияния, если не включено что-то ещё, и всегда будет загружен к тому времени, включение его по умолчанию безопасно. Но это необычные обстоятельства. Обычно начальное значение должно быть nil.

Имя easy-mmode-define-minor-mode является псевдонимом для этого макроса.

Вот пример использования define-minor-mode:

(define-minor-mode hungry-mode
  "Toggle Hungry mode.
Interactively with no argument, this command toggles the mode.
A positive prefix argument enables the mode, any other prefix
argument disables it.  From Lisp, argument omitted or nil enables
the mode, `toggle' toggles the state.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 nil
 ;; The indicator for the mode line.
 " Hungry"
 ;; The minor mode bindings.
 '(([C-backspace] . hungry-electric-delete)))

Это определяет второстепенный режим с именем «Режим голода», команду с именем hungry-mode для его переключения, переменную с именем hungry-mode, которая указывает, включен ли режим, и переменную с именем hungry-mode-map, которая хранит ключевую карту, активную при включенном режиме. Она инициализирует ключевую карту связью клавиш для C-DEL. Нет форм body — многие второстепенные режимы не нуждаются ни в чём.

Вот эквивалентный способ его записи:

(define-minor-mode hungry-mode
  "Toggle Hungry mode.
...rest of documentation as before..."
 ;; The initial value.
 :init-value nil
 ;; The indicator for the mode line.
 :lighter " Hungry"
 ;; The minor mode bindings.
 :keymap
 '(([C-backspace] . hungry-electric-delete)
   ([C-M-backspace]
    . (lambda ()
        (interactive)
        (hungry-electric-delete t)))))

Макрос: define-globalized-minor-mode global-mode mode turn-on keyword-args… body…

Это определяет глобальное переключение с именем global-mode, которое предназначено для включения или выключения локального для буфера второстепенного режима mode во всех (или некоторых; см. ниже) буферах. Оно также выполняет формы body. Для включения второстепенного режима в буфере используется функция turn-on; для выключения второстепенного режима вызывается mode с -1 в качестве аргумента.

Глобальное включение режима также влияет на буферы, созданные позднее при открытии файлов, и буферы, использующие основной режим, отличный от режима Fundamental; но оно не обнаруживает создание нового буфера в режиме Fundamental.

Это определяет параметр настройки global-mode (см. Настройка), который можно переключать в интерфейсе Настройка, чтобы включить или выключить второстепенный режим. Как и в случае с define-minor-mode, необходимо убедиться, что форма define-globalized-minor-mode оценивается каждый раз при запуске Emacs, например, указав ключевое слово :require.

Используйте :group group в keyword-args, чтобы указать пользовательскую группу для переменной режима глобального второстепенного режима.

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

Как правило, когда вы определяете глобальный второстепенный режим, вы также должны определить его неглобальную версию, чтобы люди могли использовать (или отключить) его в отдельных буферах. Это также позволяет им отключить глобально включённый второстепенный режим в определённом главном режиме, используя крючок этого режима.

Если задано ключевое слово :predicate, будет создан пользовательский параметр с тем же именем, что и переменная глобального режима, но с -modes вместо -mode в конце. Переменная используется как предикат, определяющий, в каких основных режимах должен быть активирован второстепенный режим. Допустимые значения включают t (использовать во всех основных режимах, nil (не использовать ни в одном основном режиме), или список имён режимов (или (not mode-name ...)) элементов (а также t и nil).

(c-mode (not mail-mode message-mode) text-mode)

Это означает «использовать в режимах, производных от c-mode, и не использовать в режимах, производных от message-mode или mail-mode, но использовать в режимах, производных от text-mode, и иначе не в других режимах».

((not c-mode) t)

Это означает «не использовать режимы, производные от c-mode, но использовать всюду, где это возможно».

(text-mode)

Это означает «использовать режимы, производные от text-mode, но нигде больше». (Есть неявный элемент nil в конце.)