using keyword arguments in define-minor-mode

using keyword arguments in define-minor-mode

[goncholden via Users list for the GNU Emacs text editor]

Been advised against the long obsolete form for define-minor-mode, but using keyword arguments instead. But need some examples. Particularly for indicating in the mode-line.

(define-minor-mode rich-minor-mode
"docstring"

Re: using keyword arguments in define-minor-mode

[Tassilo Horn]

goncholden via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:

> Been advised against the long obsolete form for define-minor-mode, but
> using keyword arguments instead. But need some examples. Particularly
> for indicating in the mode-line.
>
> (define-minor-mode rich-minor-mode
> "docstring"

Have a look at `C-h f define-minor-mode' which explains those keyword
arguments.

(define-minor-mode my-super-mode
  "This is the docstring."
  :lighter "ModeLineIndicator"
  ...)

Bye,
Tassilo

Re: using keyword arguments in define-minor-mode

[goncholden]

------- Original Message -------

On Friday, February 4th, 2022 at 11:38 AM, Tassilo Horn <tsdh@gnu.org> wrote:

> goncholden via Users list for the GNU Emacs text editor help-gnu-emacs@gnu.org writes:
>
> > Been advised against the long obsolete form for define-minor-mode, but
> > using keyword arguments instead. But need some examples. Particularly
> > for indicating in the mode-line.
> >
> > (define-minor-mode rich-minor-mode
> >
> > "docstring"
>
> Have a look at `C-h f define-minor-mode' which explains those keyword
> arguments.
>
> (define-minor-mode my-super-mode
> "This is the docstring."
> :lighter "ModeLineIndicator"
> ...)
>
> Bye,
> Tassilo

Tassilo, regarding :init-value, what is it, and how does it work?

Re: using keyword arguments in define-minor-mode

[Tassilo Horn]

goncholden <goncholden@protonmail.com> writes:

>> Have a look at `C-h f define-minor-mode' which explains those keyword
>> arguments.
>>
>> (define-minor-mode my-super-mode
>> "This is the docstring."
>> :lighter "ModeLineIndicator"
>> ...)
>
> Tassilo, regarding :init-value, what is it, and how does it work?

The docs say:

--8<---------------cut here---------------start------------->8---
:init-value VAL	the initial value of the mode’s variable.
		Note that the minor mode function won’t be called by setting
		this option, so the value *reflects* the minor mode’s natural
		initial state, rather than *setting* it.
		In the vast majority of cases it should be nil.
		Not used if you also specify :variable.
--8<---------------cut here---------------end--------------->8---

I'm not exactly sure how it works but would simply follow the advice of
letting it be nil, i.e., not specify :init-value t.

Looking at the occurrences of :init-value t in emacs, it's set for
minor-modes which default to "on" and are activated by other means than
the minor-mode function.  For example, mwheel.el does:

--8<---------------cut here---------------start------------->8---

(define-minor-mode mouse-wheel-mode
  "Toggle mouse wheel support (Mouse Wheel mode)."
  :init-value t
  :global t
  :group 'mouse
  ;; Remove previous bindings, if any.
  (mouse-wheel--remove-bindings)
  ;; Setup bindings as needed.
  (when mouse-wheel-mode
    (mouse-wheel--setup-bindings)))

(when mouse-wheel-mode
  (mouse-wheel--setup-bindings))
--8<---------------cut here---------------end--------------->8---

I really see no good reason for this gymnastics but guess that's
historical cruft and today you'd just write

--8<---------------cut here---------------start------------->8---
(define-minor-mode mouse-wheel-mode
  "Toggle mouse wheel support (Mouse Wheel mode)."
  :global t
  :group 'mouse
  ;; Remove previous bindings, if any.
  (mouse-wheel--remove-bindings)
  ;; Setup bindings as needed.
  (when mouse-wheel-mode
    (mouse-wheel--setup-bindings)))

(mouse-wheel-mode 1)
--8<---------------cut here---------------end--------------->8---

in order to define a default-on minor-mode.

Another example is `line-number-mode':

--8<---------------cut here---------------start------------->8---
(define-minor-mode line-number-mode
  "Toggle line number display in the mode line (Line Number mode).

Line numbers do not appear for very large buffers and buffers
with very long lines; see variables `line-number-display-limit'
and `line-number-display-limit-width'.

See `mode-line-position-line-format' for how this number is
presented."
  :init-value t :global t :group 'mode-line)
--8<---------------cut here---------------end--------------->8---

In this case, the mode doesn't do anything but toggling that variable,
but the variable `line-number-mode' is used elsewhere to check if the
line number should be displayed in the mode-line.  So here, the
minor-mode is only a convenience feature so that you can do

  M-x line-number-mode RET

instead of

  M-x set-variable RET line-number-mode RET t RET.

Another use-case for :init-value t seems to be in combination with
:initialize 'custom-initialize-delay which seems to set the mode's
variable somehow using customize which in turn will call the mode's
function.  Something like that.  Given that :initialize is not even
documented, I guess that's a usage only for emacs-internal minor-modes.
Maybe Stefan can say something about this.

Bye,
Tassilo

Re: using keyword arguments in define-minor-mode

[Kevin Vigouroux via Users list for the GNU Emacs text editor]

I don’t know if it’s enough to look at the docstring of
`define-minor-mode' when things are new.

• Emacs Lisp Ref. manual, section 23.3.3 “Defining Minor Modes”
- https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Minor-Modes.html

#+begin_quote
By default, it also defines a variable named MODE, which is set to ‘t’
or ‘nil’ by enabling or disabling the mode. The variable is initialized
to INIT-VALUE. Except in unusual circumstances (see below), this value
must be ‘nil’.
#+end_quote

#+begin_quote
The initial value must be ‘nil’ except in cases where (1) the mode is
preloaded in Emacs, or (2) it is painless for loading to enable the mode
even though the user did not request it. For instance, if the mode has
no effect unless something else is enabled, and will always be loaded by
that time, enabling it by default is harmless. But these are unusual
circumstances. Normally, the initial value must be ‘nil’.
#+end_quote
-- 
Kevin Vigouroux
Best regards