Making a function than can only be used interactively

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

[Bruno Barbier]

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.

See:
    (info "(elisp) Defining Commands")

Does it answer your question ?


Bruno

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

[Tassilo Horn]

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.

How restrictive is that! :-)

--8<---------------cut here---------------start------------->8---
(defun only-interactive ()
  (interactive)
  (if (called-interactively-p 'interactive)
      42
    (error "You may not call me")))

(only-interactive)
;;=> Debugger entered--Lisp error: (error "You may not call me")

(call-interactively 'only-interactive)
;;=> 42

(cl-letf (((symbol-function 'called-interactively-p)
           (lambda (&rest _args) t)))
  (only-interactive))
;;=> 42
--8<---------------cut here---------------end--------------->8---

So as you see, there are many ways around it.

Bye,
Tassilo

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, 19:53 by tsdh@gnu.org:

> 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.
>>
>
> How restrictive is that! :-)
>
> --8<---------------cut here---------------start------------->8---
> (defun only-interactive ()
>  (interactive)
>  (if (called-interactively-p 'interactive)
>  42
>  (error "You may not call me")))
>
> (only-interactive)
> ;;=> Debugger entered--Lisp error: (error "You may not call me")
>

Focusing on the former two `(if (called-interactively-p 'interactive)` and
`(only-interactive)`.  I would need some meatier examples.  

Using `(if (called-interactively-p 'interactive)`, would I need to put the entire 
implementations inside the if `statement`?


> (call-interactively 'only-interactive)
> ;;=> 42
>
> (cl-letf (((symbol-function 'called-interactively-p)
>  (lambda (&rest _args) t)))
>  (only-interactive))
> ;;=> 42
> --8<---------------cut here---------------end--------------->8---
>
> So as you see, there are many ways around it.
>
> Bye,
> Tassilo
>

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).
>
What I have done is make a non-interactive function, followed by an interactive wrapper.
Some experience showed me that handling everything in a single function can get extremely
complicated.


> 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>))
>
Others have suggested 

(if (called-interactively-p 'interactive)

and

(only-interactive)

But I see how your `(declare (interactive-only <foo>))` statement would work better.


> 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

[Stefan Monnier]

> Others have suggested 
>
> (if (called-interactively-p 'interactive)

`called-interactively-p` is inherently hackish and brittle, so better
stay away from it unless you're really stuck with no other way out.


        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

[Po Lu]

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

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

Then throw an error if not `called-interactively-p'.

But see the doc string for caveats.

Re: Making a function than can only be used interactively

[Stefan Monnier]

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

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:

>>> I do not want people to use the function non-interactively.
>>
>> How restrictive is that! :-)
>>
>> --8<---------------cut here---------------start------------->8---
>> (defun only-interactive ()
>>  (interactive)
>>  (if (called-interactively-p 'interactive)
>>  42
>>  (error "You may not call me")))
>>
>> (only-interactive)
>> ;;=> Debugger entered--Lisp error: (error "You may not call me")
>>
>
> Focusing on the former two `(if (called-interactively-p 'interactive)` and
> `(only-interactive)`.  I would need some meatier examples.  
>
> Using `(if (called-interactively-p 'interactive)`, would I need to put
> the entire implementations inside the if `statement`?

Yes, the 42 would become a (progn ...).  Or just do

  (interactive)
  (unless (called-interactively-p 'interactive)
    (error "You may not call me from lisp"))

at the beginning of the defun followed by your "normal" code.

But please have a look at the docs for called-interactively-p which
explain why it's usually a bad idea, e.g., my only-interactive will for
example also signal an error when used in a keyboard macro.  And as my
examples pointed out, it's easy to circumvent your restriction.

The conventional recommended way to do what you want is to just document
in your commands docstring that it's not meant to be called from lisp
using a `(declare interactive-only)' spec.  Have a look at the docstring
and source code for `next-line' as an example.

HTH,
Tassilo

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

[Christopher Dimech]

> Sent: Monday, July 04, 2022 at 10:55 PM
> From: "Tassilo Horn" <tsdh@gnu.org>
> To: carlmarcos@tutanota.com
> Cc: "Stefan Monnier" <monnier@iro.umontreal.ca>, 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> 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
> 

"interactive-only" should go far beyond a byte-compilation warning.

I suggest that "interactive-only" does actually make the function work
in an interactive-only way.  That would be much more useful, particularly
to users writing their own functions.  Currently the "interactive-only"
leads to quite some confusion.

Re: Making a function than can only be used interactively

[Stefan Monnier]

> "interactive-only" should go far beyond a byte-compilation warning.
>
> I suggest that "interactive-only" does actually make the function work
> in an interactive-only way.

What would be the benefit?


        Stefan

Re: Making a function than can only be used interactively

[Robert Pluim]

>>>>> On Mon, 04 Jul 2022 09:21:51 -0400, Stefan Monnier <monnier@iro.umontreal.ca> said:

    >> "interactive-only" should go far beyond a byte-compilation warning.
    >> 
    >> I suggest that "interactive-only" does actually make the function work
    >> in an interactive-only way.

    Stefan> What would be the benefit?

Going down in history as the person who caused peopleʼs Emacs to die a
flaming death? 😜

Robert
-- 

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

[Stefan Monnier]

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

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.

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

> Sent: Tuesday, July 05, 2022 at 1:21 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Tassilo Horn" <tsdh@gnu.org>, carlmarcos@tutanota.com, help-gnu-emacs@gnu.org
> Subject: Re: Making a function than can only be used interactively
>
> > "interactive-only" should go far beyond a byte-compilation warning.
> >
> > I suggest that "interactive-only" does actually make the function work
> > in an interactive-only way.
>
> What would be the benefit?
>
>         Stefan

There could be no benefit.  One sure thing is that there are so many ways to use
the interactive clause, that it is difficult to decide what is good design and what is
bad design.  Might be the reason some users think more assistance on its use is fundamental
to their elisp learning.  Mainly because the manual does not include any scenarios for
good design.

Speaking of design.  I can see situations when a sequence of interactive calls could depend
on the specific interactive value supplied through arguments.


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

(if (equal a 1)
  (let* (h (read-from-minibuffer ...))
  ... ))
...)

Although discouraged, the above could make sense, but completely wrong to use
non-interactively.

Perhaps there should be something beyond "An Introduction to Programming in Emacs Lisp".

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: Making a function than can only be used interactively

[Jean Louis]

* Christopher Dimech <dimech@gmx.com> [2022-07-05 00:41]:
> (defun foo (a b c)
> (interactive ...)
> 
> (if (equal a 1)
>   (let* (h (read-from-minibuffer ...))
>   ... ))
> ...)
> 
> Although discouraged, the above could make sense, but completely wrong to use
> non-interactively.

I think it is OK to use it non-interactively. 

`interactive' description says "Specify a way of parsing arguments for
interactive use of a function." 

See (info "(elisp) Using Interactive")

Here is sample function that I use:

(defun cf-hyperscope-assign-tasks-for-many (&optional id)
  "Assign tasks with information of many contacts"
  (interactive)
  (when-tabulated-id "people"
      (let* ((assignee (cf-people-search-id nil "Assign to which person? "))
	     (task (rcd-ask "Describe the task to be assigned: "))
	     (prefix (rcd-ask "Prefix for task: " "Call"))
	     (set (hyperscope-select-set)))
	(rcd-tabulated-iterate-generic 
	 id
	 (lambda (id)
	   (let* ((name (concat prefix " " (cf-full-contact-name id)))
		  (description (concat "⟦ (hyperscope-related-contact-contacts-information hyperscope-current-id) ⟧\n\n" task))
		  (hyperscope-id (hyperscope-add-generic name "" nil 31 10 set nil description nil id assignee)))
	     (hlink-update-action-status-1 hyperscope-id 2)))
	 "Assign Tasks"))))

And I may as well invoke function non-interactively, when there is
`interactive`, it means it is a command and accessible through M-x and
may be bound to keys.

-- 
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]

Tassilo Horn wrote:

>>>> 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.
>
> How restrictive is that! :-)

But it would be even more restrictive if it wasn't possible to
do ...

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

no difference between interactive and "from Lisp" (was: Re: Making a function than can only be used interactively)

[Emanuel Berg]

Stefan Monnier via Users list for the GNU Emacs text editor wrote:

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

I think in Emacs there should be no difference between
interactive and non-interactive functions. When it says in the
help or the byte-compiler says "do this instead" (or what it
says, exactly) that I think are the situations that should
be pruned.

OK, I found an example. So ... for example 

  This function [`beginning-of-buffer'] is for interactive use
  only; in Lisp code use `(goto-char (point-min))' instead.
  Probably introduced at or before Emacs version 22.1.

That's because `beginning-of-buffer' is in Elisp and
`goto-char' is in C, right?

Should be ways around it that are better, why not make
a C function that is called 'beginning-of-buffer' (i.e., the
same) that does (goto-char (point-min)) and only that, if one
wants the extra material in the current/existing
`beginning-of-buffer' that would be called something else and
that would be in Elisp. So the common case would be optimized
and that would be enforced with no difference for interactive
and non-interactive use.

And that should happen for many (all?) such cases and Elisp
should very seldom occur in the help since it should be pretty
obvious what the stuff does, and if anyone wants to use it, be
our guest in anyway s/he can think of using it.
It shouldn't matter.

OK, I'll stop :) You understood what I meant several
paragraphs ago ... *sigh*

Here is the Elisp that produces that message BTW:

  (declare (interactive-only "use `(goto-char (point-min))' instead."))

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

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: no difference between interactive and "from Lisp"

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

> That's because `beginning-of-buffer' is in Elisp and
> `goto-char' is in C, right?

No.  It's because `beginning-of-buffer' is meant for interactive use, so
it messes with the mark, for example.  Messing with the mark is a bad
idea when some piece of ELisp code goes to BOB just as part of doing
something else (e.g. just to go see what the first line looks like in
order to decide how to perform some local operation elsewhere in the
buffer).


        Stefan

Re: no difference between interactive and "from Lisp"

[Emanuel Berg]

Stefan Monnier via Users list for the GNU Emacs text editor wrote:

>> That's because `beginning-of-buffer' is in Elisp and
>> `goto-char' is in C, right?
>
> No. It's because `beginning-of-buffer' is meant for
> interactive use, so it messes with the mark, for example.
> Messing with the mark is a bad idea when some piece of ELisp
> code goes to BOB just as part of doing something else (e.g.
> just to go see what the first line looks like in order to
> decide how to perform some local operation elsewhere in the
> buffer).

OK, thanks! I'll get back to you, God willing :)

(defun bob ...

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

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

[Christopher Dimech]

> Sent: Thursday, July 07, 2022 at 8:29 AM
> From: "Jean Louis" <bugs@gnu.support>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: carlmarcos@tutanota.com, "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
>
> * 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

[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

[Emanuel Berg]

Here is an example of a more complicated interactive spec,

  (interactive
   `(,(read-string "search: [repeat] ")
     ,(or (equal current-prefix-arg '( 4))
          (equal current-prefix-arg '(64)) )
     ,(or (equal current-prefix-arg '(16))
          (equal current-prefix-arg '(64)) )
     ,@(if (use-region-p)
           (list (region-beginning) (region-end))
         (list (point-min) (point-max)) )))

Again, eval the `interactive'!

The signature is

  (defun wrap-search (str &optional case rev beg end)

Especially because 'case' and 'rev' both depends on the
`prefix-arg' I wonder if it's impossible to do with just the
interactive string, even ...

Other than that it isn't so difficult, a string is "s",
a number is "n" and the region is "r".

Note the use of the backtick just to be able to
do ,@ ... that's pretty common.

Another situation is this

  (let*((case-fold-search (not case))
        (pos (point))
        (data (if rev (list #'search-backward end beg)
                (list #'search-forward beg end) ))
        (search-f (car data))
        (search-beg (cadr data))
        (search-end (caddr data)) ) ...)

Here we see that instead of doing (if rev ... ) three times we
stash the configuration (here 3 vars) based on 'rev', then use
`car' and the "forbidden" `cadr' and `caddr' to get from that.
(Forbidden as you should it has been said only use vanilla `car'
and `cdr', with 2 or more elements instead of `car' one should
do `nth.'.

But I think the argument-free cars are interesting I
guess ....

Full source:
  https://dataswamp.org/~incal/emacs-init/wrap-search.el

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

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

Jul 8, 2022, 06:55 by yuri.v.khan@gmail.com:

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

Using a list in the most general way to use interactive.  I need specific rules 
for using a list, how to decide whether the arguments should be mandatory
or optional.


> 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

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

Jul 8, 2022, 06:55 by yuri.v.khan@gmail.com:

> 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.)
>
There seems to exist total confusion on how to use the interactive clause and how 
when to use mandatory or optional arguments, and how to handle them.  

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

When using the prefix argument, what makes sense?  A mandatory or an optional 
declaration for the prefix argument?

Re: Making a function than can only be used interactively

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

Jul 8, 2022, 12:06 by help-gnu-emacs@gnu.org:

> Jul 8, 2022, 06:55 by yuri.v.khan@gmail.com:
>
>> 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.
>>
What should one be concerned with most when deciding when and what arguments
are defined as optional.  When in non-interactive mode, or in interactive mode?



>>> 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.)
>>
> There seems to exist total confusion on how to use the interactive clause and how 
> when to use mandatory or optional arguments, and how to handle them. 
>

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

[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: Making a function than can only be used interactively

[Emanuel Berg]

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

>> 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.
>
> Using a list in the most general way to use interactive. 
> I need specific rules for using a list, how to decide
> whether the arguments should be mandatory or optional.

Rule for using a list: When it gets too complicated to use the
interactive spec string. Try that first.

Rule for mandatory: When the operation to be carried out don't
make sense without that information, then it's mandatory.
Blow up a bomb. WHEN, WHERE and what BOMB, those are
mandatory. Optional WHY. If provided, there will be
a communique (in lowercase-only letters) to the press (not
Springer media) and that will be the WHY argument. So if you
write something there that hasn't anything to do with the
attentat that will be published just as well! So be careful
and think before you act.

Optional arguments can also be fancy features and the default
is, not enabled. You may have heard of para-arithmetic
transcendence, instigated by the de facto information
conglomerate known to us only as the Dark Druids. That's the
kin of thing you realize, it's not gonna happen just
by itself ever again.

Those days are over :(

-- 
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: Making a function than can only be used interactively

[Emanuel Berg]

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

> Using a list in the most general way to use interactive.
> I need specific rules for using a list, how to decide
> whether the arguments should be mandatory or optional.

Use your mind and instinct to solve the specific situation.
When the next situation arrives, do the same. I don't think
you have to do that that many times before you don't need
rules anyway for that. Especially since it isn't really
difficult, right?

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

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