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

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...)

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: 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`?
>
>

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: [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

[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

[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

[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