About the `:variable' keyword in `define-minor-mode'

About the `:variable' keyword in `define-minor-mode'

[Xue Fuqiao]

In the docstring of `define-minor-mode':

  [...]
  :variable PLACE [...]
                PLACE can also be of the form (GET . SET), where GET is
                an expression that returns the current state, and SET
                is a function that takes one argument, the new state,
                and sets it.

I don't understand the meaning of GET.  The docstring says it returns
the current state, but where will it return?

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao

Re: About the `:variable' keyword in `define-minor-mode'

[Stefan Monnier]

> In the docstring of `define-minor-mode':
>   [...]
>   :variable PLACE [...]
>                 PLACE can also be of the form (GET . SET), where GET is
>                 an expression that returns the current state, and SET
>                 is a function that takes one argument, the new state,
>                 and sets it.

> I don't understand the meaning of GET.  The docstring says it returns
> the current state, but where will it return?

It will return it to the context?

The following expression:

     (+ 1 2)

is an expression that returns 3, and we don't care where it returns
it, really.
Does this explanation help?


        Stefan

Re: About the `:variable' keyword in `define-minor-mode'

[Michael Heerdegen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> > In the docstring of `define-minor-mode':
> >   [...]
> >   :variable PLACE [...]
> >                 PLACE can also be of the form (GET . SET), where GET is
> >                 an expression that returns the current state, and SET
> >                 is a function that takes one argument, the new state,
> >                 and sets it.
>
> > I don't understand the meaning of GET.  The docstring says it returns
> > the current state, but where will it return?
>
> It will return it to the context?

I think he wanted to know where and how it is referenced/used (in the code).

Xue, please have a look at the definition of the macro
`define-minor-mode'.  The GET part is used in the defun of the modefun,
after these lines:

       ;; The actual function.
       (defun ,modefun (&optional arg ,@extra-args)

There, the variable `mode' is bound to the GET expression.  It is mainly
used to check if the mode is on or off, but it is also `setf'ed if SET
is nil.

So, if e.g. GET is `(car foo)', the car of the value of the variable
`foo' will be looked at to decide whether the mode is turned on or off.

Does this help?


Regards,

Michael.

Re: About the `:variable' keyword in `define-minor-mode'

[Michael Heerdegen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> > In the docstring of `define-minor-mode':
> >   [...]
> >   :variable PLACE [...]
> >                 PLACE can also be of the form (GET . SET), where GET is
> >                 an expression that returns the current state, and SET
> >                 is a function that takes one argument, the new state,
> >                 and sets it.
>
> > I don't understand the meaning of GET.  The docstring says it returns
> > the current state, but where will it return?
>
> It will return it to the context?

I think he wanted to know where and how it is referenced/used (in the code).

Xue, please have a look at the definition of the macro
`define-minor-mode'.  The GET part is used in the defun of the modefun,
after these lines:

       ;; The actual function.
       (defun ,modefun (&optional arg ,@extra-args)

There, the variable `mode' is bound to the GET expression.  It is mainly
used to check if the mode is on or off, but it is also `setf'ed if SET
is nil.

So, if e.g. GET is `(car foo)', the car of the value of the variable
`foo' will be looked at to decide whether the mode is turned on or off.

Does this help?


Regards,

Michael.

Re: About the `:variable' keyword in `define-minor-mode'

[Xue Fuqiao]

Thanks for Stefan and Michael.

> > > In the docstring of `define-minor-mode':
> > >   [...]
> > >   :variable PLACE [...]
> > >                 PLACE can also be of the form (GET . SET), where GET is
> > >                 an expression that returns the current state, and SET
> > >                 is a function that takes one argument, the new state,
> > >                 and sets it.
> >
> > > I don't understand the meaning of GET.  The docstring says it returns
> > > the current state, but where will it return?
> >
> > It will return it to the context?
> I think he wanted to know where and how it is referenced/used (in the code).

That's true.

> So, if e.g. GET is `(car foo)', the car of the value of the variable
> `foo' will be looked at to decide whether the mode is turned on or off.
> Does this help?

I see, that helps.

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao