interactive-p and called-interactively-p

interactive-p and called-interactively-p

[Drew Adams]

1. The doc for these two functions is a mess - see bug #3941.

2. Beyond the doc problem, but related to it, there is a non-doc problem:
Whoever came up with the new function (in Emacs 22) `called-interactively-p' did
the wrong thing, IMO.

That function name tells nothing more nor less than the name `interactive-p'
tells. There is nothing in the _names_ that distinguishes these two functions.
Might as well have named the new function `interactive-p-2' (no, it's not a
suggestion).

This fact is a sign that the design is wrong, for if we did come up with names
that suggest the distinction, we would soon see that using two different
functions is the wrong approach. This is really one function with two minor
behavioral variants.

It would have been far better to just add an optional argument to
`interactive-p' than to create a new, similarly named function. For example:

(defun interactive-p (&optional k-macro-p)
  "Return t if the function in which this appears was called interactively.
If optional arg K-MACRO-P is non-nil, return t when called during
execution of a keyboard macro. If it is nil, return nil in that case.
...[rest of description]"

Leaving the status quo in place will bring nothing but confusion, no matter how
the doc is improved. It is better to just DTRT now.

I vote for deprecating one or the other of these two functions, combining them
by using an optional argument to express the alternative behaviors. That will go
a long way toward clarifying the intended uses.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

> It would have been far better to just add an optional argument to
> `interactive-p' than to create a new, similarly named function.

Agreed.  Any objection?


        Stefan

Re: interactive-p and called-interactively-p

[Chong Yidong]

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

>> It would have been far better to just add an optional argument to
>> `interactive-p' than to create a new, similarly named function.
>
> Agreed.  Any objection?

Since called-interactively-p has been around since Emacs 22, and the
benefit in cleanliness is rather minute, I don't think it's worth the
hassle.  We can't just remove called-interactively-p because that would
break backward compatibility, which means adding another argument to
interactive-p just means more non-useful complexity (how many people
would benefit from this anyway?).

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>>> It would have been far better to just add an optional argument to
>>> `interactive-p' than to create a new, similarly named function.
>> 
>> Agreed.  Any objection?

> Since called-interactively-p has been around since Emacs 22, and the
> benefit in cleanliness is rather minute, I don't think it's worth the
> hassle.  We can't just remove called-interactively-p because that would
> break backward compatibility, which means adding another argument to
> interactive-p just means more non-useful complexity (how many people
> would benefit from this anyway?).

It would make this cleaner and easier to explain.
Marking called-interactively-p as obsolete is easy, and
called-interactively-p is probably very rarely used nowadays outside of
Emacs's bundled packages.  Also an argument to `interactive-p' makes it
easier for people to learn about the functionality.


        Stefan

RE: interactive-p and called-interactively-p

[Drew Adams]

> >> It would have been far better to just add an optional argument to
> >> `interactive-p' than to create a new, similarly named function.
> >
> > Agreed.  Any objection?
> 
> Since called-interactively-p has been around since Emacs 22, and the
> benefit in cleanliness is rather minute,

Cleanliness?

This is about helping users (of Emacs Lisp). The existence of these two
functions, with different names that nevertheless mean the same thing (even
though the functions don't mean the same thing), just confuses their use.

Which in turn makes their use error-prone. Which complicates code and
maintenance. Which leads to further confusion about what these are for and how
to use them...

Look at the doc for this stuff - it's a mess. Think how simple the doc will be
when there is only one function with an optional arg: we'll just explain what
the arg does - QED. Compare that with the current doc (take a look, including
both doc strings and the explanations in the manual) - it's nearly
incomprehensible (and incorrect).

> I don't think it's worth the hassle.

What hassle? Just defalias `called-interactively-p' to the equivalent call of
`interactive-p' that uses the new argument appropriately. And mark it as
deprecated.

This kind of thing is nothing new. A simple mistake such as this can, and
should, be rectified. Sooner is better than later. Now is late, but later is
even later.

But fixing it *never*, simply because it was introduced in Emacs 22, is
definitely NOT TRT. By that philosophy, we should never fix any bugs that are
older than the current release. This is simply a silly design bug -
`called-interactively-p' should never have seen the light of day; and it should
be put to rest now.

> We can't just remove called-interactively-p because 
> that would break backward compatibility,

Huh? Deprecating a function is not some new invention. Defalias it now, and let
users know it is deprecated and that in the future they should use
`interactive-p' with the new arg instead. Nothing new or revolutionary about
this.

> which means adding another argument to
> interactive-p just means more non-useful complexity (how many people
> would benefit from this anyway?).

No, it was adding function `called-interactively-p' that added non-useful
complexity. This, on the contrary, is an operation in reducing complexity - for
users. Every user of the function (with the new signature) will benefit. The
code and understanding of it will be clearer.

Re: interactive-p and called-interactively-p

[Richard Stallman]

    > It would have been far better to just add an optional argument to
    > `interactive-p' than to create a new, similarly named function.

    Agreed.  Any objection?

I object.  Two different names makes it easier to remember the
difference.  An argument would be harder to remember.

The name `called-interactively-p' is good because
it relates to the use of `interactive'.  The name `interactive-p'
is confusing because it does NOT relate.

Perhaps we should make the name `interactive-p' obsolete
and make a new name, `from-user-input-p'.  This will eliminate
the confusion completely.

RE: interactive-p and called-interactively-p

[Drew Adams]

>     > It would have been far better to just add an optional 
>     > argument to `interactive-p' than to create a new,
>     > similarly named function.
> 
>     Agreed.  Any objection?
> 
> I object.  Two different names makes it easier to remember the
> difference.

That might be true, IF the names in question actually suggested the difference.

But you can understand nothing of the difference by looking at these particular
function names. All you can tell is that they are different functions (duh), but
with names that seem to say the same thing (huh?).

To understand the difference, you must then compare two doc strings that are
very similar, looking for a difference. Or read the manual and compare the
descriptions there.

In either case, the work you need to do to understand the difference is far more
than what is needed to understand what the optional arg K-MACRO-P does.

(And that's probably at least partly behind why the current doc for these is
almost incomprehensible and not entirely correct.)

> An argument would be harder to remember.

Harder to remember what, that there ARE two possible behaviors? Or WHAT those
behaviors are? This is what arguments are all about - the basic function is the
same, but its behavior depends a bit on its args.

In this case, the function names do NOT help you remember WHAT the difference
is. (The doc can't even seem to get it right.)

Having a single function with its alternative behaviors described in terms of an
optional arg is much clearer. And even seeing just the signature (with
`&optional K-MACRO-P') clarifies the meaning and helps remembering - it's
obvious from just the signature that the behavior difference is about keyboard
macros.

The most important thing to "remember" about these two functions is in fact that
they do essentially the SAME thing. They differ only in the K-MACRO-P aspect.
The basic function is the same.

So first you have to know that there are two such functions, and then you have
to look them both up, to be sure to get the right one. 

If you only know about one of the functions (I'll bet that that's the case today
for many Elisp programmers), then you risk using the wrong one (the only one you
know). If you know there are two, you still need to look them both up, to recall
which is which.

> The name `called-interactively-p' is good because
> it relates to the use of `interactive'.  The name `interactive-p'
> is confusing because it does NOT relate.

I'm not convinced, but I have no problem with that: deprecate `interactive-p' in
that case.

> Perhaps we should make the name `interactive-p' obsolete
> and make a new name, `from-user-input-p'.  This will eliminate
> the confusion completely.

OK with making one of the two functions (or both) obsolete. I don't really care
what name is retained for the merged function. 

FWIW - Of the 3 names mentioned here, my own preference would probably be first
`interactive-p', then `called-interactively-p', and last `from-user-input-p'
(not very helpful, IMO).

But I have no problem with any name that suggests what this does in a general
way. For me, the basic function it performs is to test whether the current
invocation was made interactively.

[Yes, that means invoked via `call-interactively', which is why
`called-interactively-p' is not bad. But we have already seen some confusion
surrounding `called-interactively-p' and `call-interactively'.

`interactive-p' is better in a sense, because it is higher level. Some users
might not realize that interactive invocation always means invocation through
`call-interactively', even when `call-interactively' might not appear explicitly
in the Lisp source code.

A name such as `invoked-interactively-p', which of course means the same thing
as `called-interactively-p', doesn't lend itself to such confusion.

(Of course, introducing a third name at this point does imply even more
adjustment of existing code.)]

Re: interactive-p and called-interactively-p

[Stephen J. Turnbull]

Richard Stallman writes:

 > The name `called-interactively-p' is good because
 > it relates to the use of `interactive'.

Relates, yes, but in fact called-interactively-p means "I wasn't
invoked interactively, I was called while executing a keyboard macro."
I find *that* confusing.

 > The name `interactive-p' is confusing because it does NOT relate.

`interactive-p' refers to the user interaction that invoked a command,
and in particular that arguments were gathered using an interactive
spec.  It tells the function that its arguments and environment have
been arranged for the convenience of user interaction, not as an
efficient API, and therefore they may need to be massaged.  This has
*never* been a source of confusion that I can recall.

It's been that way for two decades AFAIK.  Do you really mean to
change this now?

Re: interactive-p and called-interactively-p

[Richard Stallman]

    Relates, yes, but in fact called-interactively-p means "I wasn't
    invoked interactively, I was called while executing a keyboard macro."
    I find *that* confusing.

That seems like a misunderstanding.  `called-interactively-p' means
that the call was done using `call-interactively'.

Re: interactive-p and called-interactively-p

[Stephen J. Turnbull]

Richard Stallman writes:
 >     Relates, yes, but in fact called-interactively-p means "I wasn't
 >     invoked interactively, I was called while executing a keyboard macro."
 >     I find *that* confusing.
 > 
 > That seems like a misunderstanding.  `called-interactively-p' means
 > that the call was done using `call-interactively'.

It was, I should have read the code first, rather than relying on
discussion.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

> I object.  Two different names makes it easier to remember the
> difference.  An argument would be harder to remember.

I disagree completely: it's a lot easier to notice that the function you
use accepts an argument than to notice that there's another function
outthere doing something similar yet different.  Especially if you use
eldoc-mode, of course.

> The name `called-interactively-p' is good because
> it relates to the use of `interactive'.  The name `interactive-p'
> is confusing because it does NOT relate.

I don't care much which one is kept, but I'd like to remove one of
the two.  `interactive-p' has the advantage that it existed for a *very*
long time, whereas called-interactively-p is a new comer.  So even if we
obsolete interactive-p now, it'll take many many years before we can
actually remove it, whereas called-interactively-p is still almost
unused outside of Emacs's bundled packages.

> Perhaps we should make the name `interactive-p' obsolete and make
> a new name, `from-user-input-p'.  This will eliminate the
> confusion completely.

Even such a new name isn't very clear.  The only clear solution is to
use an additional argument passed from the interactive spec.  So I'd
rather not add yet more functions to support this hack (if you look at
the implementation of `interactive_p' it's clear that it's a nasty
hack).


        Stefan

Re: interactive-p and called-interactively-p

[Richard Stallman]

      `interactive-p' has the advantage that it existed for a *very*
    long time, whereas called-interactively-p is a new comer.

It has existed only 5 years, but I think the important point is that
its name fits its meaning.  The name interactive-p does not correspond
to its meaning, and users very often guess wrong about what it does.

    > Perhaps we should make the name `interactive-p' obsolete and make
    > a new name, `from-user-input-p'.  This will eliminate the
    > confusion completely.

    Even such a new name isn't very clear.  The only clear solution is to
    use an additional argument passed from the interactive spec.

In what sense is that the only clear solution?  I do not follow you here.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>       `interactive-p' has the advantage that it existed for a *very*
>     long time, whereas called-interactively-p is a new comer.

> It has existed only 5 years,

Yes, and during this time, compatibility to Emacs-21 and XEmacs was
still fairly important for unbundled packages, so it hasn't seen much
use outside of Emacs itself.

> but I think the important point is that its name fits its meaning.
> The name interactive-p does not correspond to its meaning, and users
> very often guess wrong about what it does.

This is clearly true, but while confusion has been common, it hasn't
been an actual problem either.  And in any case, as I mentioned, we
should rather encourage programmers to stay avoid from both of
those functions.

>> Perhaps we should make the name `interactive-p' obsolete and make
>> a new name, `from-user-input-p'.  This will eliminate the
>> confusion completely.

>     Even such a new name isn't very clear.  The only clear solution is to
>     use an additional argument passed from the interactive spec.
> In what sense is that the only clear solution?  I do not follow you here.

Because it makes it clear that you're distinguishing different notions
of "interactivity" (one of them being just "called via
call-interactively", the other being "directly called from the keyboard
rather than via a macro or some batch invocation").


        Stefan

Re: interactive-p and called-interactively-p

[Chong Yidong]

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

>> but I think the important point is that its name fits its meaning.
>> The name interactive-p does not correspond to its meaning, and users
>> very often guess wrong about what it does.
>
> This is clearly true, but while confusion has been common, it hasn't
> been an actual problem either.  And in any case, as I mentioned, we
> should rather encourage programmers to stay avoid from both of
> those functions.

I think the status quo is acceptable.  We already state, in the
doc-string of called-interactively-p, that you can do the same thing
with an interactive spec.  Further tinkering is just noise.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>>> but I think the important point is that its name fits its meaning.
>>> The name interactive-p does not correspond to its meaning, and users
>>> very often guess wrong about what it does.
>> 
>> This is clearly true, but while confusion has been common, it hasn't
>> been an actual problem either.  And in any case, as I mentioned, we
>> should rather encourage programmers to stay avoid from both of
>> those functions.

> I think the status quo is acceptable.  We already state, in the
> doc-string of called-interactively-p, that you can do the same thing
> with an interactive spec.  Further tinkering is just noise.

I think the status quo sucks.  I want to get rid of one of the
two functions.  The only question left is "which one".

The reason for it is the following: experience shows that the
distinction between interactive-p and called-interactively-p is very
subtle (it took a long time for people to realize the interactive-p
wasn't always quite right, and usually people just think "I'd like to
know if it's interactive" without thinking about what it really means).

The best way to make such a distinction clearly visible is by providing
an argument.  Even better would be to make the argument mandatory.


        Stefan

Re: interactive-p and called-interactively-p

[Richard Stallman]

    The best way to make such a distinction clearly visible is by providing
    an argument.  Even better would be to make the argument mandatory.

A mandatory argument would make people think, each time, about which
question they want to ask.  That would be good.  But it would require
changing every existing call to either of these functions.  That's
a rather high price.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>     The best way to make such a distinction clearly visible is by
>     providing an argument.  Even better would be to make the
>     argument mandatory.

> A mandatory argument would make people think, each time, about which
> question they want to ask.  That would be good.  But it would require
> changing every existing call to either of these functions.  That's
> a rather high price.

Since I don't like the status quo and want to replace those two
functions with a single one, there's going to be a price in terms of
changes.  The lower price is to obsolete called-interactively-p and add
an optional arg to interactive-p instead.  You don't seem to like this
option.  The next lower price is to obsolete interactive-p, which will
require pretty much the same number of changes as if we introduced a new
function (since 97% of the code uses interactive-p rather than
called-interactively-p).  So if we obsolete interactive-p we may as well
introduce a brand new function with a mandatory argument.  The only
problem with it would be to find a good name for it, since
called-interactively-p is already taken.


        Stefan

Re: interactive-p and called-interactively-p

[Richard Stallman]

    > A mandatory argument would make people think, each time, about which
    > question they want to ask.  That would be good.  But it would require
    > changing every existing call to either of these functions.  That's
    > a rather high price.

    Since I don't like the status quo and want to replace those two
    functions with a single one, there's going to be a price in terms of
    changes.  The lower price is to obsolete called-interactively-p and add
    an optional arg to interactive-p instead.  You don't seem to like this
    option.

If the arg is optional, it won't require or remind the programmer to
consider the issue of which question he wants to ask.

If we don't use a mandatory arg, I think the next best solution is the
one we use now: two functions with different names.

The names could be clearer than they are, but the one which is least clear
now is `interactive-p'.  That's why I proposed to change that one.

If you don't mind the size of the transient caused by the change, I think
the mandatory argument is the best design.

Re: interactive-p and called-interactively-p

[Stephen J. Turnbull]

Richard Stallman writes:

 > If you don't mind the size of the transient caused by the change, I think
 > the mandatory argument is the best design.

I don't know how many of my colleagues at XEmacs and SXEmacs will
agree, but I'd like to see that change.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>> If you don't mind the size of the transient caused by the change, I think
>> the mandatory argument is the best design.
> I don't know how many of my colleagues at XEmacs and SXEmacs will
> agree, but I'd like to see that change.

That's actually very good to hear.
So, I'd suggest the following:

- mark interactive-p as obsolete.
- add a mandatory argument to called-interactively-p.

The next best solution is:

- mark interactive-p and called-interactively-p as obsolete.
- create a new function `invoked-interactively-p' with a mandatory argument.

I prefer the first because I think called-interactively-p is the
better name.  But only the second preserves 100% backward compatibility.
This said, AFAIK called-interactively-p is not used in any Elisp package
other the ones bundled with Emacs, so I'm not sure this backward
compatibility issue is significant (which is why I prefer the first
option).


        Stefan

Re: interactive-p and called-interactively-p

[Stephen J. Turnbull]

Stefan Monnier writes:

 > So, I'd suggest the following:
 > 
 > - mark interactive-p as obsolete.
 > - add a mandatory argument to called-interactively-p.

I'd slightly prefer to keep interactive-p and give it the mandatory
argument, maybe a list of things to test a la eval-when.  As Richard
points out, "called-interactively-p" means "called by
call-interactively".  If so, adding a mandatory argument means "but
not really...".

I guess you could name the argument something like "filter-out" and
have values like "noninteractive" or "called-from-kbd-macro" for it,
but that seems awkward to me.

 > - mark interactive-p and called-interactively-p as obsolete.
 > - create a new function `invoked-interactively-p' with a mandatory argument.

-1.  That is a poor alternative in so many ways.

 > This said, AFAIK called-interactively-p is not used in any Elisp package
 > other the ones bundled with Emacs,

It's not used in any package in the XEmacs packages tree.  I believe
it may be used in AUCTeX because of this line from a ChangeLog:

auctex-11_84-import/ChangeLog:
	(TeX-doc): Use `interactive-p' instead of `called-interactively-p'

but maybe upstream changed that for XEmacs compatibility.  Some
packages may be years out of date, but most have been synched within
the last couple of years so could have used called-interactively-p.

Re: interactive-p and called-interactively-p

[Stefan Monnier]

>> So, I'd suggest the following:
>> - mark interactive-p as obsolete.
>> - add a mandatory argument to called-interactively-p.

> I'd slightly prefer to keep interactive-p and give it the mandatory
> argument, maybe a list of things to test a la eval-when.  As Richard

That would break so much existing code, that I don't think it's an option.

> points out, "called-interactively-p" means "called by
> call-interactively".  If so, adding a mandatory argument means "but
> not really...".

Both `interactive-p' and `called-interactively-p' check whether the
caller was invoked via `call-interactively', so I think it's OK to bring
them both within called-interactively-p, just with an additional arg
saying "and not from a macro or in batch mode".


        Stefan

Re: interactive-p and called-interactively-p

[Glenn Morris]

Stefan Monnier wrote:

> - mark interactive-p as obsolete.

Soon it will be simpler to mark things as non-obsolete...

Re: interactive-p and called-interactively-p

[Stephen J. Turnbull]

Glenn Morris writes:
 > Stefan Monnier wrote:
 > 
 > > - mark interactive-p as obsolete.
 > 
 > Soon it will be simpler to mark things as non-obsolete...

Hey, I like that idea!

Re: interactive-p and called-interactively-p

[MON KEY]

> So if we obsolete interactive-p we may as well
> introduce a brand new function with a mandatory argument.  The only
> problem with it would be to find a good name for it, since
> called-interactively-p is already taken.

I've been using one these in a functions' lambda list behind &optional:
interp intrp inter-p intr-p

I think these are clear, reasonably terse,  and in keeping with the
suggestions of docstring for `interactive-p':

,----
| If you want to test whether your function was called with
| `call-interactively', the way to do that is by adding an extra
| optional argument, and making the `interactive' spec specify non-nil
| unconditionally for that argument.  (`p' is a good way to do this.)'
`----

s_P

interactive-p and called-interactively-p

[Luc Teirlinck]

I know what the difference between interactive-p and
called-interactively-p is _supposed_ to be.  However is something
completely escaping me or are these two functions identical except for
their docstrings?

DEFUN ("interactive-p", Finteractive_p, Sinteractive_p, 0, 0, 0,
       doc: /* Return t if the function was run directly by user
       input.
This means that the function was called with call-interactively (which
includes being called as the binding of a key)
and input is currently coming from the keyboard (not in keyboard
       macro),
and Emacs is not running in batch mode (`noninteractive' is nil).

The only known proper use of `interactive-p' is in deciding whether to
display a helpful message, or how to display it.  If you're thinking
of using it for any other purpose, it is quite likely that you're
making a mistake.  Think: what do you want to do when the command is
called from a keyboard macro?

If you want to test whether your function was called with
`call-interactively', the way to do that is by adding an extra
optional argument, and making the `interactive' spec specify non-nil
unconditionally for that argument.  (`p' is a good way to do this.)
*/)
     ()
{
  return (INTERACTIVE && interactive_p (1)) ? Qt : Qnil;
}


DEFUN ("called-interactively-p", Fcalled_interactively_p,
Scalled_interactively_p, 0, 0, 0,
       doc: /* Return t if the function using this was called with
call-interactively.
This is used for implementing advice and other function-modifying
features of Emacs.

The cleanest way to test whether your function was called with
`call-interactively', the way to do that is by adding an extra
optional argument, and making the `interactive' spec specify non-nil
unconditionally for that argument.  (`p' is a good way to do this.)
*/)
     ()
{
  return (INTERACTIVE && interactive_p (1)) ? Qt : Qnil;
}

Re: interactive-p and called-interactively-p

[Richard Stallman]

    I know what the difference between interactive-p and
    called-interactively-p is _supposed_ to be.  However is something
    completely escaping me or are these two functions identical except for
    their docstrings?

I must have forgotten to change called-interactively-p after I copied
the code.  I'll fix that.