Re: Making a function than can only be used interactively

Re: Making a function than can only be used interactively

[Christopher Dimech]

> Jul 4, 2022, 20:45 by monnier@iro.umontreal.ca:

>>>>>            More seriously, what are you trying to gain by "mak[ing] a function
>>>>>            interactive only"?

>>>        For instance, writing an interactive wrapper function calling a non-interactive
>>>        mother function.


>    A common enough case, which you can do just fine without having to
>    prevent non-interactive calls to the interactive wrapper.

>>>        Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
>>>        like to set values interactively, while calling the function non-interactively.


>    You mean you can turn

>    (defun foo (a b c)
>    (interactive ...)
>    ...)

>    into

>    (defun foo ()
>    (interactive)
>    (let ((a ...)
>    (b ...)
>    (c ...))
>    ...))

Yes, that is what I had in mind.

>    Indeed. It's usually discouraged because it's incompatible with
>    non-interactive uses of the function, but in the case under discussion
>    you don't care about that because you already have another function to
>    use for non-interactive calls.

It is indeed incompatible with non-interactive use.  A thing that can be done
is fire the warning even when Lisp Code in not transformed into byte-code.

Although byte compilation in recommended, I wonder how often people actually
byte-compile every file.  Byte compiling will often tell you errors or warning
in your elisp code that you normally wouldn't know, but I think that running
an interactive-only function non-interactively is serious enough to insert the
warning in the warnings buffer anyway.


>>>        I am not sure if in practice that is ever desired.


>    It's done occasionally, typically in cases where it's difficult to
>    cleanly separate the part of the code that prompts the user from the
>    part that actually performs the desired operation.

>    Stefan

Re: Making a function than can only be used interactively

[Stefan Monnier]

>>    Indeed. It's usually discouraged because it's incompatible with
>>    non-interactive uses of the function, but in the case under discussion
>>    you don't care about that because you already have another function to
>>    use for non-interactive calls.
> It is indeed incompatible with non-interactive use.  A thing that can be done
> is fire the warning even when Lisp Code in not transformed into byte-code.

You could emit the warning/error during macro-expansion, indeed.
Something like:

    (defun foo (a b c)
      (interactive ...)
      (declare (compiler-macro (lambda (_) (error "Called non-interactively"))))
      ...)

Not sure what's the benefit, still.

> Although byte compilation in recommended, I wonder how often people actually
> byte-compile every file.

`flymake-mode` will run the compiler for you to get those warnings right
while you're writing the code.  If people don't see the warning because
they don't compile their files, then let's fix it by trying to convince
them to compile their files, which will come with a lot of other benefits.

> Byte compiling will often tell you errors or warning in your elisp
> code that you normally wouldn't know, but I think that running an
> interactive-only function non-interactively is serious enough to
> insert the warning in the warnings buffer anyway.

Usually calling an interactive-only function non-interactively is not
serious *at all* and very often it's The Right Thing to do.


        Stefan

Re: Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Tuesday, July 05, 2022 at 9:45 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: tsdh@gnu.org, help-gnu-emacs@gnu.org
> Subject: Re: Making a function than can only be used interactively
>
> >>    Indeed. It's usually discouraged because it's incompatible with
> >>    non-interactive uses of the function, but in the case under discussion
> >>    you don't care about that because you already have another function to
> >>    use for non-interactive calls.
> > It is indeed incompatible with non-interactive use.  A thing that can be done
> > is fire the warning even when Lisp Code in not transformed into byte-code.
>
> You could emit the warning/error during macro-expansion, indeed.
> Something like:
>
>     (defun foo (a b c)
>       (interactive ...)
>       (declare (compiler-macro (lambda (_) (error "Called non-interactively"))))
>       ...)
>
> Not sure what's the benefit, still.
>
> > Although byte compilation in recommended, I wonder how often people actually
> > byte-compile every file.
>
> `flymake-mode` will run the compiler for you to get those warnings right
> while you're writing the code.  If people don't see the warning because
> they don't compile their files, then let's fix it by trying to convince
> them to compile their files, which will come with a lot of other benefits.
>
> > Byte compiling will often tell you errors or warning in your elisp
> > code that you normally wouldn't know, but I think that running an
> > interactive-only function non-interactively is serious enough to
> > insert the warning in the warnings buffer anyway.
>
> Usually calling an interactive-only function non-interactively is not
> serious *at all* and very often it's The Right Thing to do.
>
>         Stefan

Depends whether the person coding that function thinks it is.  What can he
do then?  Issue warning as you suggested with `declare`?

Re: Making a function than can only be used interactively

[Stefan Monnier via Users list for the GNU Emacs text editor]

> Depends whether the person coding that function thinks it is.
> What can he do then?  Issue warning as you suggested with `declare`?

I don't think we can answer this in the abstract.  So, we'd first need
to have some concrete scenario before we can start discussing it.


        Stefan

RE: [External] : Re: Making a function than can only be used interactively

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1003 bytes --]

> > Depends whether the person coding that function thinks it is.
> > What can he do then?  Issue warning as you suggested with `declare`?
> 
> I don't think we can answer this in the abstract.  So, we'd first need
> to have some concrete scenario before we can start discussing it.

Yup.  Has any concrete description been presented
in this thread that makes clear what the real
problem to be solved is - the use case behind the
question?

I've only browsed the thread, so apologies if some
actual problem (and its "why") has been specified.
From just perusing, I haven't noticed any.

As I guessed before, I'm still guessing (so far):

   there's an X-Y problem under the covers here
   somewhere...)

What is it that OP is _really_ trying to do/solve?

I'm guessing that's behind an inability by folks
who've coded zillions of functions to understand
what's being asked/requested.  What's the problem?

https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem

[-- Attachment #2: winmail.dat --]
[-- Type: application/ms-tnef, Size: 14371 bytes --]

Re: RE: [External] : Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Wednesday, July 06, 2022 at 2:02 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Stefan Monnier" <monnier@iro.umontreal.ca>
> Cc: "'Help-Gnu-Emacs (help-gnu-emacs@gnu.org)'" <help-gnu-emacs@gnu.org>
> Subject: RE: [External] : Re: Making a function than can only be used interactively
>
> > > Depends whether the person coding that function thinks it is.
> > > What can he do then?  Issue warning as you suggested with `declare`?
> >
> > I don't think we can answer this in the abstract.  So, we'd first need
> > to have some concrete scenario before we can start discussing it.
>
> Yup.  Has any concrete description been presented
> in this thread that makes clear what the real
> problem to be solved is - the use case behind the
> question?

The filling of arguments could be difficult if a sequence of interactive
prompt depend on previous values.

One thing that has been discussed is the following

(defun foo ()
(interactive)
(let ((a ...)
(b ...)
(c ...))
...))

RE: RE: [External] : Making a function than can only be used interactively

[Drew Adams]

> > Has any concrete description been presented
> > in this thread that makes clear what the real
> > problem to be solved is - the use case behind
> > the question?
> 
> The filling of arguments could be difficult
> if a sequence of interactive prompt depend
> on previous values.

Hard to guess what you mean.  Example?

What's to prevent someone from calling the
function (whatever it is) with appropriate
arguments, whether or not some of them depend
on others?

> One thing that has been discussed is the following
> (defun foo ()
>  (interactive)
>  (let ((a ...)
>        (b ...)
>        (c ...))
>   ...))

Didn't Stefan show that only to indicate that
you can prompt for values in the body of a
function, instead of (or in addition to) doing
so in an `interactive' spec?

IOW, presumably he was suggesting that some of
the "..." to provide values for a, b, and c
could come from prompting a user - IOW, making
the function interactive regardless of how
it's called.

I don't see what that has to do with any
problem of "filling arguments" when calling
from Lisp.

Sorry, but so far I'm not grasping what the
problem is - what OP is really trying to do.

But again, I only skimmed the thread.  If you
think the question / use case is clear to
others then please ignore my feedback.

FW: RE: RE: [External] : Making a function than can only be used interactively

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 2352 bytes --]

I guess this was maybe intended for the help list?

-----Original Message-----
From: Christopher Dimech <dimech@gmx.com> 
Sent: Tuesday, July 5, 2022 2:15 PM
To: Drew Adams <drew.adams@oracle.com>
>
> > > Has any concrete description been presented
> > > in this thread that makes clear what the real
> > > problem to be solved is - the use case behind
> > > the question?
> >
> > The filling of arguments could be difficult
> > if a sequence of interactive prompt depend
> > on previous values.
>
> Hard to guess what you mean.  Example?
>
> What's to prevent someone from calling the
> function (whatever it is) with appropriate
> arguments, whether or not some of them depend
> on others?
>
> > One thing that has been discussed is the following
> > (defun foo ()
> >  (interactive)
> >  (let ((a ...)
> >        (b ...)
> >        (c ...))
> >   ...))
>
> Didn't Stefan show that only to indicate that
> you can prompt for values in the body of a
> function, instead of (or in addition to) doing
> so in an `interactive' spec?

Yes.  That strategy could easily make a function inappropriate
for non-interactive use.  The result would not necessarily be
a result of bad design.

> IOW, presumably he was suggesting that some of
> the "..." to provide values for a, b, and c
> could come from prompting a user - IOW, making
> the function interactive regardless of how
> it's called.
>
> I don't see what that has to do with any
> problem of "filling arguments" when calling
> from Lisp.
>
> Sorry, but so far I'm not grasping what the
> problem is - what OP is really trying to do.

The OP wants to make the function purely interactive.
But at a low-level, you can't have a function that
can be called interactively and not non-interactively.

The sensible way out is for the OP to include its inappropriateness
for use in elisp code in the documentation.  Either that, or using
a specific part-name separated by "--" for the function name, as
indicator that function is inappropriate for elisp code.  Emacs
has done this strategy before.

> But again, I only skimmed the thread.  If you
> think the question / use case is clear to
> others then please ignore my feedback.

Although I understand it, the result would either be unreliable or
too cumbersome for actual use.





[-- Attachment #2: winmail.dat --]
[-- Type: application/ms-tnef, Size: 15644 bytes --]

Re: FW: RE: RE: [External] : Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Wednesday, July 06, 2022 at 10:40 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "'Help-Gnu-Emacs (help-gnu-emacs@gnu.org)'" <help-gnu-emacs@gnu.org>
> Cc: "Christopher Dimech" <dimech@gmx.com>
> Subject: FW: RE: RE: [External] :  Making a function than can only be used interactively
>
> I guess this was maybe intended for the help list?

It was.  Thanks.

> -----Original Message-----
> From: Christopher Dimech <dimech@gmx.com>
> Sent: Tuesday, July 5, 2022 2:15 PM
> To: Drew Adams <drew.adams@oracle.com>
> >
> > > > Has any concrete description been presented
> > > > in this thread that makes clear what the real
> > > > problem to be solved is - the use case behind
> > > > the question?
> > >
> > > The filling of arguments could be difficult
> > > if a sequence of interactive prompt depend
> > > on previous values.
> >
> > Hard to guess what you mean.  Example?
> >
> > What's to prevent someone from calling the
> > function (whatever it is) with appropriate
> > arguments, whether or not some of them depend
> > on others?
> >
> > > One thing that has been discussed is the following
> > > (defun foo ()
> > >  (interactive)
> > >  (let ((a ...)
> > >        (b ...)
> > >        (c ...))
> > >   ...))
> >
> > Didn't Stefan show that only to indicate that
> > you can prompt for values in the body of a
> > function, instead of (or in addition to) doing
> > so in an `interactive' spec?
>
> Yes.  That strategy could easily make a function inappropriate
> for non-interactive use.  The result would not necessarily be
> a result of bad design.
>
> > IOW, presumably he was suggesting that some of
> > the "..." to provide values for a, b, and c
> > could come from prompting a user - IOW, making
> > the function interactive regardless of how
> > it's called.
> >
> > I don't see what that has to do with any
> > problem of "filling arguments" when calling
> > from Lisp.
> >
> > Sorry, but so far I'm not grasping what the
> > problem is - what OP is really trying to do.
>
> The OP wants to make the function purely interactive.
> But at a low-level, you can't have a function that
> can be called interactively and not non-interactively.
>
> The sensible way out is for the OP to include its inappropriateness
> for use in elisp code in the documentation.  Either that, or using
> a specific part-name separated by "--" for the function name, as
> indicator that function is inappropriate for elisp code.  Emacs
> has done this strategy before.
>
> > But again, I only skimmed the thread.  If you
> > think the question / use case is clear to
> > others then please ignore my feedback.
>
> Although I understand it, the result would either be unreliable or
> too cumbersome for actual use.
>
>
>
>
>

Re: Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Tuesday, July 05, 2022 at 10:05 AM
> From: "Christopher Dimech" <dimech@gmx.com>
> To: "Stefan Monnier" <monnier@iro.umontreal.ca>
> Cc: tsdh@gnu.org, help-gnu-emacs@gnu.org
> Subject: Re: Making a function than can only be used interactively
>
>
>
> > Sent: Tuesday, July 05, 2022 at 9:45 AM
> > From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> > To: "Christopher Dimech" <dimech@gmx.com>
> > Cc: tsdh@gnu.org, help-gnu-emacs@gnu.org
> > Subject: Re: Making a function than can only be used interactively
> >
> > >>    Indeed. It's usually discouraged because it's incompatible with
> > >>    non-interactive uses of the function, but in the case under discussion
> > >>    you don't care about that because you already have another function to
> > >>    use for non-interactive calls.
> > > It is indeed incompatible with non-interactive use.  A thing that can be done
> > > is fire the warning even when Lisp Code in not transformed into byte-code.
> >
> > You could emit the warning/error during macro-expansion, indeed.
> > Something like:
> >
> >     (defun foo (a b c)
> >       (interactive ...)
> >       (declare (compiler-macro (lambda (_) (error "Called non-interactively"))))
> >       ...)
> >
> > Not sure what's the benefit, still.

I am not confident the declare command will always work.

Not for

(defun foo ()
(interactive)
(let ((a ...)
(b ...)
(c ...))
...))


> > > Although byte compilation in recommended, I wonder how often people actually
> > > byte-compile every file.
> >
> > `flymake-mode` will run the compiler for you to get those warnings right
> > while you're writing the code.  If people don't see the warning because
> > they don't compile their files, then let's fix it by trying to convince
> > them to compile their files, which will come with a lot of other benefits.
> >
> > > Byte compiling will often tell you errors or warning in your elisp
> > > code that you normally wouldn't know, but I think that running an
> > > interactive-only function non-interactively is serious enough to
> > > insert the warning in the warnings buffer anyway.
> >
> > Usually calling an interactive-only function non-interactively is not
> > serious *at all* and very often it's The Right Thing to do.
> >
> >         Stefan
>
> Depends whether the person coding that function thinks it is.  What can he
> do then?  Issue warning as you suggested with `declare`?
>
>

Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Is it possible to make an interactive function than can only be used interactively?

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 3, 2022, 19:28 by brubar.cs@gmail.com:

>
> carlmarcos--- via Users list for the GNU Emacs text editor
> <help-gnu-emacs@gnu.org> writes:
>
>> Is it possible to make an interactive function than can only be used interactively?
>>
>
> I'm not sure I understand your question. A function, that may be called
> interactively, is called a "command" in Emacs.  And a command can
> definitely be called interactively, either by using it's name (using
> M-x) or binding it to a key.
>
I do not want people to use the function non-interactively.


> See:
>  (info "(elisp) Defining Commands")
>
> Does it answer your question ?
>
>
> Bruno
>

Re: Making a function than can only be used interactively

[Stefan Monnier via Users list for the GNU Emacs text editor]

> I do not want people to use the function non-interactively.

An interactive call is fundamentally a combination of "run the
interactive spec to get the args, and then call the function with those
args".  So, in a sense you can't avoid it.

But you can discourage non-interactive calls in various ways, depending
on how important you think it is.  The most standard way is to use

    (declare (interactive-only <foo>))

so that the compiler will emit a warning when it sees a non-interactive
call to that function (<foo> is the replacement you recommend for
non-interactive calls).

A more "forceful" way is to wrap your interactive function inside
a trivial keyboard macro:

    (defalias 'my-command
              (vector (lambda (...)
                        (interactive ..)
                        ...)))

this way `my-command` is a valid command but it's not a valid function.
I'd not recommend such a measure, tho.


        Stefan

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 3, 2022, 20:14 by help-gnu-emacs@gnu.org:

>> I do not want people to use the function non-interactively.
>>
>
> An interactive call is fundamentally a combination of "run the
> interactive spec to get the args, and then call the function with those
> args".  So, in a sense you can't avoid it.
>
> But you can discourage non-interactive calls in various ways, depending
> on how important you think it is.  The most standard way is to use
>
>  (declare (interactive-only <foo>))
>
> so that the compiler will emit a warning when it sees a non-interactive
> call to that function (<foo> is the replacement you recommend for
> non-interactive calls).
>
I need some clarification about  (<foo> is the replacement you recommend for
non-interactive calls).

Thought that (declare (interactive-only <foo>)) specifies <foo> to work only interactively.
Thus, what is the "replacement" about?

Re: Making a function than can only be used interactively

[Stefan Monnier via Users list for the GNU Emacs text editor]

> Thought that (declare (interactive-only <foo>)) specifies <foo> to
> work only interactively.  Thus, what is the "replacement" about?

No, the function that's declared to be `interactive-only` is the
function in which you place this `declare`.  The <foo> is used in the
warning's text to say something like "<blabla> is for interactive only;
use <foo> instead".

A `grep '(interactive-only' **/*.el` in Emacs's source code will give
you some examples.


        Stefan

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 3, 2022, 22:01 by help-gnu-emacs@gnu.org:

>> Thought that (declare (interactive-only <foo>)) specifies <foo> to
>> work only interactively.  Thus, what is the "replacement" about?
>>
>
> No, the function that's declared to be `interactive-only` is the
> function in which you place this `declare`.  The <foo> is used in the
> warning's text to say something like "<blabla> is for interactive only;
> use <foo> instead".
>
> A `grep '(interactive-only' **/*.el` in Emacs's source code will give
> you some examples.
>
I have seen 

(declare (interactive-only t))

(interactive-only "use `font-lock-ensure' or `font-lock-flush' instead."))

(declare (interactive-only delete-char))

I am still unsure because I have done

(declare (interactive-only arktika-automated-workbench))

before `(interactive "P")` in a function `arktika-workbench`.

`arktika-automated-workbench` is the non-interactive function whilst
 `arktika-workbench` is an interactive wrapper.

Yet when I do `(arktika-workbench)` in my init file, the interactive function
`arktika-workbench` still gets executed.


>
>  Stefan
>

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 4, 2022, 01:13 by monnier@iro.umontreal.ca:

>> Yet when I do `(arktika-workbench)` in my init file, the interactive function
>> `arktika-workbench` still gets executed.
>>
>
> Why wouldn't it?  As I said the `interactive-only` declaration only
> causes the byte-compiler (and hence flymake) to warn about
> non-interactive uses of the function.
>
Have also done a simpler function 

(defun test ()
  "TODO"
  (declare (interactive-only arktika-automated-workbench))
  (interactive)
  (message "*** test") )

(test)

Loading emacs I can see that the string "*** test" is being printed.  I am using Emacs 27.2.

Re: Making a function than can only be used interactively

[Tassilo Horn]

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

>>> Yet when I do `(arktika-workbench)` in my init file, the interactive
>>> function `arktika-workbench` still gets executed.
>>
>> Why wouldn't it?  As I said the `interactive-only` declaration only
>> causes the byte-compiler (and hence flymake) to warn about
>> non-interactive uses of the function.
>>
> Have also done a simpler function 
>
> (defun test ()
>   "TODO"
>   (declare (interactive-only arktika-automated-workbench))
>   (interactive)
>   (message "*** test") )
>
> (test)
>
> Loading emacs I can see that the string "*** test" is being printed. 
> I am using Emacs 27.2.

Sure, the function will be executed.  As Stefan said, the only effect of
the declare spec is that byte-compiling the file will cause a warning
that `test' is only meant for interactive use.

Bye,
Tassilo

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 4, 2022, 10:55 by tsdh@gnu.org:

> carlmarcos--- via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:
>
>>>> Yet when I do `(arktika-workbench)` in my init file, the interactive
>>>> function `arktika-workbench` still gets executed.
>>>>
>>>
>>> Why wouldn't it?  As I said the `interactive-only` declaration only
>>> causes the byte-compiler (and hence flymake) to warn about
>>> non-interactive uses of the function.
>>>
>> Have also done a simpler function 
>>
>> (defun test ()
>>   "TODO"
>>   (declare (interactive-only arktika-automated-workbench))
>>   (interactive)
>>   (message "*** test") )
>>
>> (test)
>>
>> Loading emacs I can see that the string "*** test" is being printed. 
>> I am using Emacs 27.2.
>>
>
> Sure, the function will be executed.  As Stefan said, the only effect of
> the declare spec is that byte-compiling the file will cause a warning
> that `test' is only meant for interactive use.
>
> Bye,
> Tassilo
>
Only after byte-compile of a file?  So there is no way to actually make a function interactive only?

Re: Making a function than can only be used interactively

[Stefan Monnier]

> Only after byte-compile of a file? 
> So there is no way to actually make a function interactive only?

Please define what it is you mean by "make a function interactive only".

Do you mean that it should be illegal to write code that calls the
function directly, so whoever writes it can be sued?
Would it be acceptable for someone to just think about writing such code
as long as they don't actually write it?

More seriously, what are you trying to gain by "mak[ing] a function
interactive only"?  Usually, the reason why one might want to make
a function "interactive only" is that code that calls this function is
probably incorrect and would likely be served better by some
other function.  So the purpose is to help people write better code.
For this reason the declaration only has an effect in terms of
byte-compiler warnings: those who don't bother to byte-compile their
code presumably don't care about the quality of their code anyway.

Emacs doesn't offer any pre-defined way to really enforce that
a function is only used interactively, and in large parts this is
because, as a matter of design principle, Emacs makes no effort to stop
people from shooting themselves in the foot (instead, it tries to make
it easier for people not to shoot themselves in the foot).


        Stefan

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 4, 2022, 19:40 by monnier@iro.umontreal.ca:

>> Only after byte-compile of a file? 
>> So there is no way to actually make a function interactive only?
>>
>
> Please define what it is you mean by "make a function interactive only".
>
> Do you mean that it should be illegal to write code that calls the
> function directly, so whoever writes it can be sued?
> Would it be acceptable for someone to just think about writing such code
> as long as they don't actually write it?
>
> More seriously, what are you trying to gain by "mak[ing] a function
> interactive only"?  
>
>
For instance, writing an interactive wrapper function calling a non-interactive
mother function.

Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
 like to set values interactively, while calling the function non-interactively.  One can
 achieve more or less the same effect with setting values of local variables outside
 the interactive expression.  In this scenario, running the function non-interactively would
still force interactive input from the minibuffer.

I am not sure if in practice that is ever desired.

> Usually, the reason why one might want to make
> a function "interactive only" is that code that calls this function is
> probably incorrect and would likely be served better by some
> other function.  So the purpose is to help people write better code.
> For this reason the declaration only has an effect in terms of
> byte-compiler warnings: those who don't bother to byte-compile their
> code presumably don't care about the quality of their code anyway.
>
> Emacs doesn't offer any pre-defined way to really enforce that
> a function is only used interactively, and in large parts this is
> because, as a matter of design principle, Emacs makes no effort to stop
> people from shooting themselves in the foot (instead, it tries to make
> it easier for people not to shoot themselves in the foot).
>
>
>  Stefan
>

Re: Making a function than can only be used interactively

[Jean Louis]

* carlmarcos--- via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2022-07-04 22:52]:
> Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
>  like to set values interactively, while calling the function non-interactively.  One can
>  achieve more or less the same effect with setting values of local variables outside
>  the interactive expression.  In this scenario, running the function non-interactively would
> still force interactive input from the minibuffer.
> 
> I am not sure if in practice that is ever desired.

(interactive &optional ARG-DESCRIPTOR &rest MODES) -- this makes the
function a command that may be tied to a key, and it helps in
specifying the arguments to the function. 

In this context function may be run as command, or by pressing a
key. However, it does not really mean it need to interact with user,
not at all. It does not need to ask nothing of the user. In fact, it
can just interactively, during Emacs session be called by user with
M-x or by using a key. Beyond that, function may remain quite silent
without interactivity.

The above is one specific context where word "interactive" is used as
in function (interactive).

It does not exclude the other context that any function without
(interactive) may do interactive activities, like ask user
interactively for input.

Remember, there are 2 different contexts. One does not exclude the other.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Wednesday, July 06, 2022 at 12:07 PM
> From: "Jean Louis" <bugs@gnu.support>
> To: carlmarcos@tutanota.com
> Cc: "Stefan Monnier" <monnier@iro.umontreal.ca>, "Tassilo Horn" <tsdh@gnu.org>, help-gnu-emacs@gnu.org
> Subject: Re: Making a function than can only be used interactively
>
> * carlmarcos--- via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2022-07-04 22:52]:
> > Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
> >  like to set values interactively, while calling the function non-interactively.  One can
> >  achieve more or less the same effect with setting values of local variables outside
> >  the interactive expression.  In this scenario, running the function non-interactively would
> > still force interactive input from the minibuffer.
> > 
> > I am not sure if in practice that is ever desired.
> 
> (interactive &optional ARG-DESCRIPTOR &rest MODES) -- this makes the
> function a command that may be tied to a key, and it helps in
> specifying the arguments to the function. 
> 
> In this context function may be run as command, or by pressing a
> key. However, it does not really mean it need to interact with user,
> not at all. It does not need to ask nothing of the user. In fact, it
> can just interactively, during Emacs session be called by user with
> M-x or by using a key. Beyond that, function may remain quite silent
> without interactivity.
> 
> The above is one specific context where word "interactive" is used as
> in function (interactive).
> 
> It does not exclude the other context that any function without
> (interactive) may do interactive activities, like ask user
> interactively for input.

If one does not mind interactive activities with the minibuffer for
a function without the interactive clause.
 
> Remember, there are 2 different contexts. One does not exclude the other.
> 
> -- 
> Jean
> 
> Take action in Free Software Foundation campaigns:
> https://www.fsf.org/campaigns
> 
> In support of Richard M. Stallman
> https://stallmansupport.org/
> 
>

Re: Making a function than can only be used interactively

[Jean Louis]

* Christopher Dimech <dimech@gmx.com> [2022-07-06 23:00]:
> 
> > Sent: Wednesday, July 06, 2022 at 12:07 PM
> > From: "Jean Louis" <bugs@gnu.support>
> > To: carlmarcos@tutanota.com
> > Cc: "Stefan Monnier" <monnier@iro.umontreal.ca>, "Tassilo Horn" <tsdh@gnu.org>, help-gnu-emacs@gnu.org
> > Subject: Re: Making a function than can only be used interactively
> >
> > * carlmarcos--- via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2022-07-04 22:52]:
> > > Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
> > >  like to set values interactively, while calling the function non-interactively.  One can
> > >  achieve more or less the same effect with setting values of local variables outside
> > >  the interactive expression.  In this scenario, running the function non-interactively would
> > > still force interactive input from the minibuffer.
> > > 
> > > I am not sure if in practice that is ever desired.
> > 
> > (interactive &optional ARG-DESCRIPTOR &rest MODES) -- this makes the
> > function a command that may be tied to a key, and it helps in
> > specifying the arguments to the function. 
> > 
> > In this context function may be run as command, or by pressing a
> > key. However, it does not really mean it need to interact with user,
> > not at all. It does not need to ask nothing of the user. In fact, it
> > can just interactively, during Emacs session be called by user with
> > M-x or by using a key. Beyond that, function may remain quite silent
> > without interactivity.
> > 
> > The above is one specific context where word "interactive" is used as
> > in function (interactive).
> > 
> > It does not exclude the other context that any function without
> > (interactive) may do interactive activities, like ask user
> > interactively for input.
> 
> If one does not mind interactive activities with the minibuffer for
> a function without the interactive clause.

1) That means for me, you did not understand what is interactive
function. Just read docstring. 

2) Nowhere it says that function without (interactive) cannot
interact with user. 

Numbers above (1) and (2) are different contexts. A word such as
"interactive" has different meanings. 

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 6, 2022, 20:29 by bugs@gnu.support:

> * Christopher Dimech <dimech@gmx.com> [2022-07-06 23:00]:
>
>>
>> > Sent: Wednesday, July 06, 2022 at 12:07 PM
>> > From: "Jean Louis" <bugs@gnu.support>
>> > To: carlmarcos@tutanota.com
>> > Cc: "Stefan Monnier" <monnier@iro.umontreal.ca>, "Tassilo Horn" <tsdh@gnu.org>, help-gnu-emacs@gnu.org
>> > Subject: Re: Making a function than can only be used interactively
>> >
>> > * carlmarcos--- via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2022-07-04 22:52]:
>> > > Technically, you can use `completing-read` and `read-from-minibuffer` if you'd also
>> > >  like to set values interactively, while calling the function non-interactively.  One can
>> > >  achieve more or less the same effect with setting values of local variables outside
>> > >  the interactive expression.  In this scenario, running the function non-interactively would
>> > > still force interactive input from the minibuffer.
>> > > 
>> > > I am not sure if in practice that is ever desired.
>> > 
>> > (interactive &optional ARG-DESCRIPTOR &rest MODES) -- this makes the
>> > function a command that may be tied to a key, and it helps in
>> > specifying the arguments to the function. 
>> > 
>> > In this context function may be run as command, or by pressing a
>> > key. However, it does not really mean it need to interact with user,
>> > not at all. It does not need to ask nothing of the user. In fact, it
>> > can just interactively, during Emacs session be called by user with
>> > M-x or by using a key. Beyond that, function may remain quite silent
>> > without interactivity.
>> > 
>> > The above is one specific context where word "interactive" is used as
>> > in function (interactive).
>> > 
>> > It does not exclude the other context that any function without
>> > (interactive) may do interactive activities, like ask user
>> > interactively for input.
>>
>> If one does not mind interactive activities with the minibuffer for
>> a function without the interactive clause.
>>
>
> 1) That means for me, you did not understand what is interactive
> function. Just read docstring. 
>
> 2) Nowhere it says that function without (interactive) cannot
> interact with user. 
>
It is a way to pass arguments with user prompt.


> Numbers above (1) and (2) are different contexts. A word such as
> "interactive" has different meanings. 
>
What different meanings?  

-- 

> Jean
>
> Take action in Free Software Foundation campaigns:
> https://www.fsf.org/campaigns
>
> In support of Richard M. Stallman
> https://stallmansupport.org/
>

Re: Making a function than can only be used interactively

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

>> A word such as "interactive" has different meanings.
>
> What different meanings?

So interactive/non-interactive 101 ...

M-x - that's interactive

Keystroke - interactive!

"interactive" means (interactive "nX: \n") is used to assign
the argument values to the formal parameters.

Compare "from Lisp" or non-interactive use which looks like
this:

(from-lisp x) - non-interactive, i.e. (interactive "...")
isn't used, but you see that x is provided so no worries.

A function that is interactive is also called a command!

That's all I know ... what more do you want?

  You gotta give me more and more
  Cuz you're the girl that I adore
  --Zodiac Evermore, Netherlands 1996
  https://dataswamp.org/~incal/vidz/evermore-kate.mp4

-- 
underground experts united
https://dataswamp.org/~incal

Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

-- 
 Sent with Tutanota, enjoy secure & ad-free emails. 



Jul 7, 2022, 21:28 by incal@dataswamp.org:

> carlmarcos--- via Users list for the GNU Emacs text editor wrote:
>
>>> A word such as "interactive" has different meanings.
>>>
>>
>> What different meanings?
>>
>
> So interactive/non-interactive 101 ...
>
> M-x - that's interactive
>
> Keystroke - interactive!
>
> "interactive" means (interactive "nX: \n") is used to assign
> the argument values to the formal parameters.
>
> Compare "from Lisp" or non-interactive use which looks like
> this:
>
> (from-lisp x) - non-interactive, i.e. (interactive "...")
> isn't used, but you see that x is provided so no worries.
>
> A function that is interactive is also called a command!
>
> That's all I know ... what more do you want?
>

I want to know a few specific things.  If I want to use the prefix argument, I should include
a variable in the argument list, right?  Let us call the variable "prefix".  Now, should the prefix
 be  mandatory or optional?  Should it always be the first argument?  

(defun funname (prefix arg-a arg-b)
  "docstring"
  (interactive "P\ns Name:\n s City")
  (message "executed funname"))


>  You gotta give me more and more
>  Cuz you're the girl that I adore
>  --Zodiac Evermore, Netherlands 1996
>  https://dataswamp.org/~incal/vidz/evermore-kate.mp4
>
> -- 
> underground experts united
> https://dataswamp.org/~incal
>

Re: Making a function than can only be used interactively

[Yuri Khan]

On Fri, 8 Jul 2022 at 05:14, carlmarcos--- via Users list for the GNU
Emacs text editor <help-gnu-emacs@gnu.org> wrote:

> I want to know a few specific things.  If I want to use the prefix argument, I should include
> a variable in the argument list, right?  Let us call the variable "prefix".  Now, should the prefix
>  be  mandatory or optional?  Should it always be the first argument?
>
> (defun funname (prefix arg-a arg-b)
>   "docstring"
>   (interactive "P\ns Name:\n s City")
>   (message "executed funname"))

It does not matter for interactive use. Your (interactive) spec, if it
were written correctly[see below], would describe three arguments, and
Emacs would therefore pass three arguments to your function.

‘&optional’ comes into play if you use this function
non-interactively, from Lisp:

    (defun funname (prefix arg-a arg-b)
       nil)
    (funname 0 1 2)
    ⇒ nil
    (funname)
    ⇒ (wrong-number-of-arguments (lambda (prefix arg-a arg-b) nil) 0)

    (defun funname (&optional prefix arg-a arg-b)
       nil)
    (funname 0 1 2)
    ⇒ nil
    (funname)
    ⇒ nil

Now about (interactive) spec syntax: you have three spaces there. The
one immediately after the ‘\n’ breaks things — the first character of
an argument specification specifies the way it is produced, and space
is not a valid code letter. The other two spaces (after ‘s’) become
part of the prompt so the prompt is displayed not at the window edge
but one character to the right. Your spec should be:

    (interactive "P\nsName:\nsCity")

Re: Making a function than can only be used interactively

[Emanuel Berg]

Yuri Khan wrote:

> It does not matter for interactive use. [...] ‘&optional’
> comes into play if you use this function non-interactively,
> from Lisp

No, it matters. One example how it matters is that optional
arguments defaults to nil.

Check out this file and in particular example 4 which doesn't
make sense to me?

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/dwim.el

;; DWIM example 1, from Lisp ignore region if set

(defun test-dwim (&optional beg end)
  (interactive (when (use-region-p)
                 (list (region-beginning) (region-end)) ))
  (or beg (setq beg (point-min))) ; or (point)
  (or end (setq end (point-max)))
  ;; insert code here
  ;; now let's just make a list to do something
  (list beg end) )

;; example 2, use the region if available from Lisp as well

(defun test-dwim-2 (&optional beg end)
  (interactive (when (use-region-p)
                 (list (region-beginning) (region-end)) ))
  (or beg (setq beg (if (use-region-p) (region-beginning) (point-min))))
  (or end (setq end (if (use-region-p) (region-end)       (point-max))))
  (list beg end) )

;; example 3, one call to `use-region-p' is enough

(defun test-dwim-3 (re &optional beg end)
  (interactive `(,(read-regexp "re: ")
                 ,@(when (use-region-p)
                     (list (region-beginning) (region-end)) )))
  (or beg (setq beg (point-min)))
  (or end (setq end (point-max)))
  (message "%s" (list re beg end)) )

;; example 4, let's do that with the `interactive' spec
;; string. but without `use-region-p' it doesn't reset after
;; I clear the region, or that's what I thought happened
;; anyway :) so this doesn't work as intended, which
;; `test-dwim-3' does, supposedly the worse one.

(defun test-dwim-4 (re &optional beg end)
  (interactive "sre: \nr")
  (or beg (setq beg (point-min)))
  (or end (setq end (point-max)))
  (message "%s" (list re beg end)) )

;; test the interface

(when nil
  (save-excursion
    (set-mark   10)
    (goto-char 500)
    (call-interactively #'test-dwim) ) ; (10  500)
  (call-interactively #'test-dwim)     ; ( 1 2867)
  (test-dwim 30 90)                    ; (30   90)
  (test-dwim)                          ; ( 1 2867)
)

;; example function

(defun count-chars (&optional beg end)
  (interactive (when (use-region-p)
                 (list (region-beginning) (region-end)) ))
  (let*((bg (or beg (point-min)))
        (ed (or end (point-max)))
        (df (- ed bg)) )
    (prog1
        df
      (message "%d" df) )))

;; Test the example function:
;;
:;   [try these with and without a region]
;;
;;   (call-interactively #'count-chars)
;;   (count-chars)
;;
;;   [this will always be the same tho]
;;
;;   (count-chars 10 40)
;;
;; Note:
;;   A common mistake in Elisp is that optional formal
;;   parameters aren't sent as arguments when called from
;;   Lisp, they are then nil but are used as for example an
;;   integer, as in:
;;
;;     (when (and (<= 0 width) (<= width 648)) ... ) ; DNC
;;
;; The test method is to call the function every way possible:
;;   1. interactively with a region
;;   2. ditto w/o
;;   3. From Lisp with arguments
;;   4. ditto w/o
;;   .. ..

-- 
underground experts united
https://dataswamp.org/~incal

Re: Making a function than can only be used interactively

[Yuri Khan]

On Fri, 8 Jul 2022 at 13:31, Emanuel Berg <incal@dataswamp.org> wrote:

> > It does not matter for interactive use. [...] ‘&optional’
> > comes into play if you use this function non-interactively,
> > from Lisp
>
> No, it matters. One example how it matters is that optional
> arguments defaults to nil.

You’re right, with an interactive specification that evaluates to a
list it matters, because the list you return may or may not have as
many arguments as the function takes.

My point was that in the specific case of a three-argument function
and a three-item string-valued interactive specification, &optional
does not matter for interactive use.


> Check out this file and in particular example 4 which doesn't
> make sense to me?
>
> ;; DWIM example 1, from Lisp ignore region if set
> ;; example 2, use the region if available from Lisp as well
>
> (defun test-dwim (&optional beg end)
>   (interactive (when (use-region-p)
>                  (list (region-beginning) (region-end)) ))

Here you have two cases. If the region is active, you produce a
two-element list, otherwise, a 0-element list. The function signature
allows 0..2 arguments, so it works in either case.

> ;; example 3, one call to `use-region-p' is enough
>
> (defun test-dwim-3 (re &optional beg end)
>   (interactive `(,(read-regexp "re: ")
>                  ,@(when (use-region-p)
>                      (list (region-beginning) (region-end)) )))

Mostly same, except you build a list of 3 or 1 elements, and the
function accepts 1..3 arguments.

> ;; example 4, let's do that with the `interactive' spec
> ;; string. but without `use-region-p' it doesn't reset after
> ;; I clear the region, or that's what I thought happened
> ;; anyway :) so this doesn't work as intended, which
> ;; `test-dwim-3' does, supposedly the worse one.
>
> (defun test-dwim-4 (re &optional beg end)
>   (interactive "sre: \nr")

Here you use a string interactive spec which always produces 3
elements. In non-interactive use, it will work if called as
(test-dwim-4 "^foo$"), (test-dwim-4 "^foo$" 42), or (test-dwim-4
"^foo$" 42 69).

As to your “clearing” the region, Emacs always maintains the point and
mark positions, and the ‘r’ interactive spec code ignores the region
activation flag and always passes the point and mark. (This could be
considered a bug, but I see no good alternative behavior, except maybe
passing two nils if the region is not active.)

Re: Making a function than can only be used interactively

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 6:55 PM
> From: "Yuri Khan" <yuri.v.khan@gmail.com>
> To: "help-gnu-emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: Making a function than can only be used interactively
>
> On Fri, 8 Jul 2022 at 13:31, Emanuel Berg <incal@dataswamp.org> wrote:
> 
> > > It does not matter for interactive use. [...] ‘&optional’
> > > comes into play if you use this function non-interactively,
> > > from Lisp
> >
> > No, it matters. One example how it matters is that optional
> > arguments defaults to nil.
> 
> You’re right, with an interactive specification that evaluates to a
> list it matters, because the list you return may or may not have as
> many arguments as the function takes.
> 
> My point was that in the specific case of a three-argument function
> and a three-item string-valued interactive specification, &optional
> does not matter for interactive use.


It looks as if the easiest understanding of mandatory versus optional
function arguments occurs when using a function interactively.

For the interactive case, it is quite complicated, depending on whether
the function uses code characters or a list.

My proposition would be to include the corresponding explanation on using
in either the "Emacs Lisp Reference Manual" or the "Introduction to Programming
in Emacs Lisp".

RE: [External] : Re: Making a function than can only be used interactively

[Drew Adams]

> It looks as if the easiest understanding of mandatory versus optional
> function arguments occurs when using a function interactively.
> 
> For the interactive case, it is quite complicated, depending on whether
> the function uses code characters or a list.
> 
> My proposition would be to include the corresponding explanation on
> using in either the "Emacs Lisp Reference Manual" or the "Introduction to
> Programming in Emacs Lisp".

Dunno whether it's a coincidence (I'm guessing no),
but in the past couple of weeks there've been a
boatload of similar questions on emacs.SE.  Here
are some of them:

What is a raw prefix argument?

https://emacs.stackexchange.com/q/13886

Numeric prefix argument for use with interactive command

https://emacs.stackexchange.com/q/72365

Changing of function arguments

https://emacs.stackexchange.com/q/72393

Using current prefix argument value

https://emacs.stackexchange.com/q/72425

Function arguments and interactive

https://emacs.stackexchange.com/q/72428

Getting prefix as argument

https://emacs.stackexchange.com/q/72454
_____

(I voted to close some of them as duplicates.)

Anyway, (I think) I see confusion there similar to
what (I think) I'm seeing here now.

FWIW, here are some comments I wrote to the last of
those questions.  That doesn't seem to have done
much good.  But maybe they'll help here.
____

1. There's no connection between an argument being
   optional and it being provided as a prefix
   argument - none.

2. The only implication of an arg being mandatory or
   optional is for calling the function.  If it's
   mandatory then omitting it raises an error;
   otherwise, no error. That's all.

3. Using a prefix arg does not necessarily pass an
   argument to the function.

   A prefix arg is not necessarily an arg to the
   function, and vice versa.

   A prefix arg need not be optional.

   And you can use C-u with M-x.

   I suggest you read the Emacs manual about prefix
   args:

   https://www.gnu.org/software/emacs/manual/html_node/elisp/Prefix-Command-Arguments.html 

   Start by `C-h k C-u'.

   A prefix arg is used (can be used) by the
   following command.  It is not necessarily
   associated with any argument to that function.
   You can think of it as a global variable, if you
   like - the function has access to it, but it
   need not be one of the function's arguments.
____

Back to this mail thread...

Instead of looking for some general guideline for
when to use a prefix arg, or when to make this or
that argument optional, my advice is to just learn
what each thingie is/_does_.

Learn how a prefix arg behaves (raw and numeric).
Learn how an optional arg behaves.  Learn some of
the predefined chars for a string arg to
`interactive'.  Learn how to give a list arg to
`interactive'.

Play with those things.  Once you know what each
does you'll know what you can do with them.  And
you'll know when you might want to use this or
that thingie.  Only you know what you want, but
you need to know what the tools in your toolbox
look like and do.

This whole discussion feels like a quest for
advice about when to use the number one or zero -
or a negative number or a positive number or ...
There is no single "when".  There's just knowing
the properties/behaviors of things.	
____

tl;dr (too late, I know):

Don't ask when to use X.  Just get to know X.
When and how and why to use it will come to you
when you know it.

(Just one opinion.)

RE: [External] : Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 8, 2022, 20:29 by drew.adams@oracle.com:

>> It looks as if the easiest understanding of mandatory versus optional
>> function arguments occurs when using a function interactively.
>>
>> For the interactive case, it is quite complicated, depending on whether
>> the function uses code characters or a list.
>>
>> My proposition would be to include the corresponding explanation on
>> using in either the "Emacs Lisp Reference Manual" or the "Introduction to
>> Programming in Emacs Lisp".
>>
>
> Dunno whether it's a coincidence (I'm guessing no),
> but in the past couple of weeks there've been a
> boatload of similar questions on emacs.SE.  Here
> are some of them:
>
I saw them and got the same kind of problem of how to write interactive function.
Quite complicated thing.


> What is a raw prefix argument?
>
> https://emacs.stackexchange.com/q/13886
>
> Numeric prefix argument for use with interactive command
>
> https://emacs.stackexchange.com/q/72365
>
> Changing of function arguments
>
> https://emacs.stackexchange.com/q/72393
>
> Using current prefix argument value
>
> https://emacs.stackexchange.com/q/72425
>
> Function arguments and interactive
>
> https://emacs.stackexchange.com/q/72428
>
> Getting prefix as argument
>
> https://emacs.stackexchange.com/q/72454
> _____
>
> (I voted to close some of them as duplicates.)
>
> Anyway, (I think) I see confusion there similar to
> what (I think) I'm seeing here now.
>
> FWIW, here are some comments I wrote to the last of
> those questions.  That doesn't seem to have done
> much good.  But maybe they'll help here.
> ____
>
> 1. There's no connection between an argument being
>  optional and it being provided as a prefix
>  argument - none.
>
> 2. The only implication of an arg being mandatory or
>  optional is for calling the function.  If it's
>  mandatory then omitting it raises an error;
>  otherwise, no error. That's all.
>
> 3. Using a prefix arg does not necessarily pass an
>  argument to the function.
>
>  A prefix arg is not necessarily an arg to the
>  function, and vice versa.
>
>  A prefix arg need not be optional.
>
>  And you can use C-u with M-x.
>
>  I suggest you read the Emacs manual about prefix
>  args:
>
>  https://www.gnu.org/software/emacs/manual/html_node/elisp/Prefix-Command-Arguments.html 
>
>  Start by `C-h k C-u'.
>
>  A prefix arg is used (can be used) by the
>  following command.  It is not necessarily
>  associated with any argument to that function.
>  You can think of it as a global variable, if you
>  like - the function has access to it, but it
>  need not be one of the function's arguments.
> ____
>
> Back to this mail thread...
>
> Instead of looking for some general guideline for
> when to use a prefix arg, or when to make this or
> that argument optional, my advice is to just learn
> what each thingie is/_does_.
>
> Learn how a prefix arg behaves (raw and numeric).
> Learn how an optional arg behaves.  Learn some of
> the predefined chars for a string arg to
> `interactive'.  Learn how to give a list arg to
> `interactive'.
>
> Play with those things.  Once you know what each
> does you'll know what you can do with them.  And
> you'll know when you might want to use this or
> that thingie.  Only you know what you want, but
> you need to know what the tools in your toolbox
> look like and do.
>
> This whole discussion feels like a quest for
> advice about when to use the number one or zero -
> or a negative number or a positive number or ...
> There is no single "when".  There's just knowing
> the properties/behaviors of things. 
> ____
>
> tl;dr (too late, I know):
>
> Don't ask when to use X.  Just get to know X.
> When and how and why to use it will come to you
> when you know it.
>
> (Just one opinion.)
>

RE: [External] : Re: Making a function than can only be used interactively

[Drew Adams]

>> Dunno whether it's a coincidence (I'm guessing no),
>> but in the past couple of weeks there've been a
>> boatload of similar questions on emacs.SE. Here
>> are some of them:
>
> I saw them and got the same kind of problem of how
> to write interactive function.

I can tell - by your just now writing this, even after
reading my message:

> I thought that because the prefix argument i[s] used
> first (using C-u N myfunc) then it also has to be
> the first argument in the function declaration.

So you _saw_ my comments on emacs.SE, but it's not
clear that you _read_ them.

Do yourself a favor.  Read this  s l o w l y  . . .

    A "prefix argument" is NOT an argument
    to the function (command).  It's NOT.

That is, it _need not be_.  It's _not automatically_
used as any of the function's args.  It _could_ be
passed as one or more of the function's args.  There's
NO necessary or logical connection between the "prefix
argument" and the function's arguments.

If this isn't yet clear, please read that again.  And
again ... till it's clear.

A prefix argument results from a _user action_.  It
makes a value available when the function's code is
evaluated.  If that value isn't passed as one of the
function's arguments then the function body (or code
it invokes...) can obtain it using the global variable
`current-prefix-arg' - see `C-h v current-prefix-arg'.

And you say:

> because the prefix argument i[s] used first (using
> C-u N myfunc)

No, it's not "used first".  It's _not used at all_
... unless the function's code actually, explicitly
uses it somehow.  A user can hit `C-u' all day long
with zero effect, if the current command doesn't make
any use of the prefix arg.

How can a command (function) explicitly use the prefix
arg?  (1) in an `interactive' spec, (2) in the body,
or (3) by passing its value as an argument.

To use the prefix arg in an `interactive' spec you can
(1) use `P' or `p' in a string argument (any number of
times), or (2) use `current-prefix-arg' in a list arg
(any number of times).

To use it in the body explicitly, use variable
`current-prefix-arg'.

How else can a function use the prefix arg?  (3) Pass
its value as one or more of the function's args.

> Quite complicated thing.

No, not really.  I think you've just been misled by
the name "prefix ARGUMENT".

Nothing to be ashamed of.  But now you know - it is
NOT AN ARGUMENT to the command - not unless (1) the
command's `interactive' spec provides its value as
one of the command's arguments OR (2) code that
invokes the command (function) passes it as one
of the arguments.

I don't think any of us have been able to help much
by replying to vague requests for guidance about
when to use this or that (optional arg, prefix arg,
`interactive', ...).

And the reason, I think, is because the request is
misguided (an X-Y question).  I'm guessing it's the
name "prefix argument" that's got you (and perhaps
others) twisted in a knot by mis-suggesting that it
represents something that has something to do with
an argument to the command (function).  IT DOESN'T.

Now go outside and have fun. ;-)
___

Rereading the Emacs manual about "prefix argument"
now, I can see where someone might get the wrong
idea.  It tries to present a command to users as
something more abstract than the Lisp (or C) function
that implements it.  And so it talks about a "prefix
argument" being provided to the command first, and
"minibuffer args" possibly being provided afterward.

IOW, from a user, non-Lisp point of view, you can
think that you first provide an "argument" to a
command using `C-u' etc.  And then the command might
prompt you for other info ("arguments") in the
minibuffer.

I think that's what that language is about.  But it
can (apparently) create a disconnect when someone
then tries to move to a Lisp understanding, with the
notion of a command as a function (an interactive
function), which gets passed arguments.
___


[
NOTE: If some code in a command (in the `interactive'
spec or in the body), or in any code invoked by the
command, invokes another command interactively, or lets
a user invoke another command interactively, then the
use of that other command invocation redefines the
`current-prefix-arg' value.

And yes, _that_ can get a bit complicated.  If you're
interested in this, and you feel up to it, then dig
into the Elisp manual, node `Command Loop':

https://www.gnu.org/software/emacs/manual/html_node/elisp/Command-Loop.html

]

RE: [External] : Re: Making a function than can only be used interactively

[carlmarcos--- via Users list for the GNU Emacs text editor]

-- 
 Sent with Tutanota, enjoy secure & ad-free emails. 



Jul 8, 2022, 22:17 by drew.adams@oracle.com:

>>> Dunno whether it's a coincidence (I'm guessing no),
>>> but in the past couple of weeks there've been a
>>> boatload of similar questions on emacs.SE. Here
>>> are some of them:
>>>
>>
>> I saw them and got the same kind of problem of how
>> to write interactive function.
>>
>
> I can tell - by your just now writing this, even after
> reading my message:
>
>> I thought that because the prefix argument i[s] used
>> first (using C-u N myfunc) then it also has to be
>> the first argument in the function declaration.
>>
>
> So you _saw_ my comments on emacs.SE, but it's not
> clear that you _read_ them.
>
> Do yourself a favor.  Read this  s l o w l y  . . .
>
>  A "prefix argument" is NOT an argument
>  to the function (command).  It's NOT.
>
> That is, it _need not be_.  It's _not automatically_
> used as any of the function's args.  It _could_ be
> passed as one or more of the function's args.  There's
> NO necessary or logical connection between the "prefix
> argument" and the function's arguments.
>
> If this isn't yet clear, please read that again.  And
> again ... till it's clear.
>
> A prefix argument results from a _user action_.  It
> makes a value available when the function's code is
> evaluated.  If that value isn't passed as one of the
> function's arguments then the function body (or code
> it invokes...) can obtain it using the global variable
> `current-prefix-arg' - see `C-h v current-prefix-arg'.
>
> And you say:
>
>> because the prefix argument i[s] used first (using
>> C-u N myfunc)
>>
>
> No, it's not "used first".  It's _not used at all_
> ... unless the function's code actually, explicitly
> uses it somehow.  A user can hit `C-u' all day long
> with zero effect, if the current command doesn't make
> any use of the prefix arg.
>
> How can a command (function) explicitly use the prefix
> arg?  (1) in an `interactive' spec, (2) in the body,
> or (3) by passing its value as an argument.
>
> To use the prefix arg in an `interactive' spec you can
> (1) use `P' or `p' in a string argument (any number of
> times), or (2) use `current-prefix-arg' in a list arg
> (any number of times).
>
> To use it in the body explicitly, use variable
> `current-prefix-arg'.
>
> How else can a function use the prefix arg?  (3) Pass
> its value as one or more of the function's args.
>
>> Quite complicated thing.
>>
>
> No, not really.  I think you've just been misled by
> the name "prefix ARGUMENT".
>
> Nothing to be ashamed of.  But now you know - it is
> NOT AN ARGUMENT to the command - not unless (1) the
> command's `interactive' spec provides its value as
> one of the command's arguments OR (2) code that
> invokes the command (function) passes it as one
> of the arguments.
>
> I don't think any of us have been able to help much
> by replying to vague requests for guidance about
> when to use this or that (optional arg, prefix arg,
> `interactive', ...).
>
> And the reason, I think, is because the request is
> misguided (an X-Y question).  I'm guessing it's the
> name "prefix argument" that's got you (and perhaps
> others) twisted in a knot by mis-suggesting that it
> represents something that has something to do with
> an argument to the command (function).  IT DOESN'T.
>
> Now go outside and have fun. ;-)
> ___
>
> Rereading the Emacs manual about "prefix argument"
> now, I can see where someone might get the wrong
> idea.  It tries to present a command to users as
> something more abstract than the Lisp (or C) function
> that implements it.  And so it talks about a "prefix
> argument" being provided to the command first, and
> "minibuffer args" possibly being provided afterward.
>
Yes, that was exactly why I had the impression that the list should have
arg storing the prefix argument as the first argument to the function.  And that
it has to be optional because a user can decide not to call the interactive function
with C-u.


> IOW, from a user, non-Lisp point of view, you can
> think that you first provide an "argument" to a
> command using `C-u' etc.  And then the command might
> prompt you for other info ("arguments") in the
> minibuffer.
>
Yes, I thought that way.


> I think that's what that language is about.  But it
> can (apparently) create a disconnect when someone
> then tries to move to a Lisp understanding, with the
> notion of a command as a function (an interactive
> function), which gets passed arguments.
>

Correct.  Found it very hard to go from reading to an actual implementation.
I also found no way to get the equivalent of Code Character "P" if the function
 includes an arg that stores the prefix within a list 

For instance

(defun guling (&optional prefix a b)
  "Docstring"

  (interactive
   (cond

    ((equal current-prefix-arg 2)
     (list
      () ;  What should one put here??? 
      (read-from-minibuffer "a: ")
      (read-from-minibuffer "b: "))))) 

(processing))
  


> ___
>
>
> [
> NOTE: If some code in a command (in the `interactive'
> spec or in the body), or in any code invoked by the
> command, invokes another command interactively, or lets
> a user invoke another command interactively, then the
> use of that other command invocation redefines the
> `current-prefix-arg' value.
>
> And yes, _that_ can get a bit complicated.  If you're
> interested in this, and you feel up to it, then dig
> into the Elisp manual, node `Command Loop':
>
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Command-Loop.html
>
> ]
>

RE: [External] : Re: Making a function than can only be used interactively

[Drew Adams]

> I also found no way to get the equivalent of
> Code Character "P" if the function includes
> an arg that stores the prefix within a list

"P" stands for `current-prefix-arg'.  Just put
that in the list.

> (defun guling (&optional prefix a b) "Docstring"
>  (interactive
>   (cond
>    ((equal current-prefix-arg 2)
>     (list
>      () ;  What should one put here???

       current-prefix-arg

(or even just 2 in this case, since you know it's 2)

>      (read-from-minibuffer "a: ")
>      (read-from-minibuffer "b: "))))) 
>  (processing))

If you want to pass the value of the raw prefix
arg as one of the arguments to your command (in
this case the arg PREFIX), then just put its
value in the list arg of `interactive' (in this
case as the first list element).

You really owe it to yourself, if you're starting
to write some Elisp code, to dig into the fine
manual Emacs that gives you (with `C-h i'):

"An Introduction to Programming in Emacs Lisp"

https://www.gnu.org/software/emacs/manual/html_node/eintr/

Re: [External] : Re: Making a function than can only be used interactively

[Emanuel Berg]

Drew Adams wrote:

>   A "prefix argument" is NOT an argument to the function
>   (command) [...]
>
> That is, it _need not be_ [...]

That is, it SHOULD be [...]

-- 
underground experts united
https://dataswamp.org/~incal

Re: [External] : Re: Making a function than can only be used interactively

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

> I saw them and got the same kind of problem of how to write
> interactive function. Quite complicated thing.

Just do it, what function is it you want and how far did you get?

-- 
underground experts united
https://dataswamp.org/~incal

Re: [External] : Re: Making a function than can only be used interactively

[Emanuel Berg]

Drew Adams wrote:

> but in the past couple of weeks there've been a
> boatload of similar questions on emacs.SE

The Emacs world is not that big ...

> 1. There's no connection between an argument being optional
>    and it being provided as a prefix argument - none.
>
> 2. The only implication of an arg being mandatory or
>    optional is for calling the function. If it's mandatory
>    then omitting it raises an error; otherwise, no error.
>    That's all

Good points, and the others, but that's not all, that's easy -
to do something sensible with it can be tricky. Don't know how
one succeeds at that tho, maybe one just do something that
works, use it, and refine it, including the interface, little
by little when one get better intuition how it works, what can
be improved and so on?

After doing that one will see certain patterns that reappear
and such things can then be instantly brought into new stuff
that's similar, so the process gets more involved the further
you go ...

> A prefix arg is not necessarily an arg to the function, and
> vice versa.

But it's a good idea for clarity, documentation and also how
do you call it from Lisp in a neat way without it if you want
the same functionality?

> A prefix arg need not be optional.

But it's useful for defaults and the optional arguments
default themselves if not set so it's an easy way to do that.

> Don't ask when to use X. Just get to know X. When and how
> and why to use it will come to you when you know it.

100%

-- 
underground experts united
https://dataswamp.org/~incal

RE: [External] : Re: Making a function than can only be used interactively

[Drew Adams]

> > Only after byte-compile of a file?
> > So there is no way to actually make a function interactive only?
> 
> Please define what it is you mean by "make a function interactive
> only".
> 
> Do you mean that it should be illegal to write code that calls the
> function directly, so whoever writes it can be sued?
> Would it be acceptable for someone to just think about writing such
> code as long as they don't actually write it?
> 
> More seriously, what are you trying to gain by "mak[ing] a function
> interactive only"?  Usually, the reason why one might want to make
> a function "interactive only" is that code that calls this function is
> probably incorrect and would likely be served better by some
> other function.  So the purpose is to help people write better code.
> For this reason the declaration only has an effect in terms of
> byte-compiler warnings: those who don't bother to byte-compile their
> code presumably don't care about the quality of their code anyway.
> 
> Emacs doesn't offer any pre-defined way to really enforce that
> a function is only used interactively, and in large parts this is
> because, as a matter of design principle, Emacs makes no effort to stop
> people from shooting themselves in the foot (instead, it tries to make
> it easier for people not to shoot themselves in the foot).

Indeed.

(My crystal ball whispers there's an X-Y problem
under the covers here somewhere...)