read-file-name-predicate

read-file-name-predicate

[Drew Adams]

`read-file-name-predicate' is a Lisp variable. It's doc says only that it is
the current predicate used by built-in function `read-file-name-internal'.
This is the only doc about it, and it gives the impression that it is only
an internal variable for a built-in function. If that were true, then why
would it be a Lisp variable instead of a C variable?

The C code shows that `read-file-name-predicate' is in fact set to the value
of the PREDICATE arg to `read-file-name', but that is not documented
anywhere - shouldn't it be?  `read-file-name-predicate' has an external,
Lisp behavior: During completion, Lisp code can check what the predicate is
or even change the predicate. Shouldn't that be documented?

IOW, it seems like this variable is currently half way between being
internal and external. The doc suggests that it is internal, but the code
shows that you can examine it and change it from Lisp.

Re: read-file-name-predicate

[Stefan Monnier]

> IOW, it seems like this variable is currently half way between being
> internal and external.  The doc suggests that it is internal, but the code
> shows that you can examine it and change it from Lisp.

Being visible from Lisp doesn't mean it's external.  Lots of elisp packages
have internal variables as well.


        Stefan

Re: read-file-name-predicate

[Juanma Barranquero]

On 3/7/07, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Being visible from Lisp doesn't mean it's external.  Lots of elisp packages
> have internal variables as well.

You're right, but I suppose Drew's point is: why it is visible from
Lisp *at all*? It is not used anywhere from lisp/*.el, and the only
src/* to use it is fileio.c.

I see Kim added it relatively recently, along with
read-file-name-function, which is used in ido. Perhaps he had some
intended use in mind?

             Juanma

RE: read-file-name-predicate

[Drew Adams]

> > Being visible from Lisp doesn't mean it's external.  Lots of 
> > elisp packages have internal variables as well.

So substitute "accessible from Lisp" where you feel I mispoke by using "external". I was trying to contrast internal to C with accessible from Lisp. (One level's "internal" is another level's "external"...)
 
> You're right, but I suppose Drew's point is: why it is visible from
> Lisp *at all*? It is not used anywhere from lisp/*.el, and the only
> src/* to use it is fileio.c.

My point is that it is currently entre deux chaises. Either 1) it should be, as it is, accessible from Lisp, in which case it should be documented, or 2) it should be inaccessible from Lisp. (Yes, I do realize that not everything that is accessible from Lisp is documented.)

I personally prefer #1. This being accessible from Lisp is a useful feature. I already use it in one of my libraries in a way similar to using `minibuffer-completion-predicate. I think that these two variables should in fact be treated in the same way: keep them accessible from Lisp, and document them similarly.

> I see Kim added it relatively recently, along with
> read-file-name-function, which is used in ido. Perhaps he had some
> intended use in mind?

I don't know what use Kim intended originally, but I've found it useful. Accessing `minibuffer-completion-predicate' is useless when it comes to file-name completion, and `read-file-name-predicate' fills the bill nicely. Without it, I know of no way to get at that predicate during completion, either to examine it or to modify it.

Re: read-file-name-predicate

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 7 Mar 2007 08:31:59 -0800
> 
> My point is that it is currently entre deux chaises. Either 1) it should be, as it is, accessible from Lisp, in which case it should be documented, or 2) it should be inaccessible from Lisp. (Yes, I do realize that not everything that is accessible from Lisp is documented.)

There are internal functions written in Lisp and internal Lisp
variables.  They are frequently not documented too well because it is
frequently hard to document them without explaining a lot of Emacs
internals.  This is perfectly normal.

I don't know if in this specific case the variable is a left-over from
something we don't need anymore; I hope Kim will answer that.  But
your general point -- that Lisp variables should all be documented to
the degree that every Emacs user should understand -- is not valid (as
a generality).

RE: read-file-name-predicate

[Drew Adams]

> > My point is that it is currently entre deux chaises. Either 1)
> > it should be, as it is, accessible from Lisp, in which case it
> > should be documented, or 2) it should be inaccessible from Lisp.
> > (Yes, I do realize that not everything that is accessible from
> > Lisp is documented.)
>
> There are internal functions written in Lisp and internal Lisp
> variables.  They are frequently not documented too well because it is
> frequently hard to document them without explaining a lot of Emacs
> internals.  This is perfectly normal.
>
> I don't know if in this specific case the variable is a left-over from
> something we don't need anymore; I hope Kim will answer that.  But
> your general point -- that Lisp variables should all be documented to
> the degree that every Emacs user should understand -- is not valid (as
> a generality).

Eli, you are arguing against the wind again.

That was *not* my "general point". I did *not* make that point at all, in
fact. I never said anything about "all" Lisp variables needing to be
documented. I explicitly said "Yes, I do realize that *not* everything that
is accessible from
Lisp is documented."

I argued only for documenting *this* variable, not all Lisp variables. The
argument I gave for documenting *this* variable is that it is useful for
Lisp programmers. The current doc does not say what it is for or what it
does. To use it, users will need to know that info. It's really very simple:
just say that this is the predicate supplied to `read-file-name'.

I also said nothing about "internal Lisp variables".

My point about internal/external was to point out that this variable, whose
doc says only that it is for use by a C-coded Lisp function, is not, in
fact, only accessible or only useful for that built-in function. It is just
as useful as the variable `minibuffer-completion-predicate', which is
prominently documented, and which is also used by a built-in function. To
me, these two variables are parallel.

Is this clear enough:

*IF*, as I hope, this is to remain a Lisp variable, and *IF*, as I claim, it
is useful to users in the same way that `minibuffer-completion-predicate' is
useful, *THEN* it should be documented similarly to
`minibuffer-completion-predicate'.

*IF* someone decides that this should be usable only by the built-in Lisp
function `read-file-name', *THEN* perhaps it should not be a Lisp variable
at all. A Lisp variable whose doc says, in effect, "There is no reason that
I am a Lisp variable, I don't do anything anyway, and you must not use me"
is silly.

Re: read-file-name-predicate

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 7 Mar 2007 09:14:28 -0800
> 
> That was *not* my "general point".

You could have fooled me.

Anyway, I commented on the general issue, not this specific variable.

> *IF*, as I hope, this is to remain a Lisp variable, and *IF*, as I claim, it
> is useful to users in the same way that `minibuffer-completion-predicate' is
> useful, *THEN* it should be documented similarly to
> `minibuffer-completion-predicate'.
> 
> *IF* someone decides that this should be usable only by the built-in Lisp
> function `read-file-name', *THEN* perhaps it should not be a Lisp variable
> at all.

These are not the only possibilities.  There are others, as Richard
and Stefan explained.

> A Lisp variable whose doc says, in effect, "There is no reason that
> I am a Lisp variable, I don't do anything anyway, and you must not use me"
> is silly.

That is not what the current doc string of this variable says.

Re: read-file-name-predicate

[Richard Stallman]

    I don't know if in this specific case the variable is a left-over from
    something we don't need anymore; I hope Kim will answer that.  But
    your general point -- that Lisp variables should all be documented to
    the degree that every Emacs user should understand -- is not valid (as
    a generality).

That is correct.  Some C features need Lisp variables (and Lisp
primitive functions) that are internal and we do not need to document
them.  In some cases we do not WANT Lisp programmers to use these
internal functions and variables.

Re: read-file-name-predicate

[Kim F. Storm]

Eli Zaretskii <eliz@gnu.org> writes:

> I don't know if in this specific case the variable is a left-over from
> something we don't need anymore; I hope Kim will answer that.

Because read-file-name-internal need to specbind it:

  count = SPECPDL_INDEX ();
  specbind (intern ("completion-ignore-case"),
	    read_file_name_completion_ignore_case ? Qt : Qnil);
  specbind (intern ("minibuffer-completing-file-name"), Qt);
  specbind (intern ("read-file-name-predicate"),
	    (NILP (predicate) ? Qfile_exists_p : predicate));

I guess it could have been done some other way, but this seemed
the easiest way to do it at the time.  

Let's not change it now.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: read-file-name-predicate

[Richard Stallman]

    My point is that it is currently entre deux chaises. Either 1) it
    should be, as it is, accessible from Lisp, in which case it should
    be documented, or 2) it should be inaccessible from Lisp. (Yes, I
    do realize that not everything that is accessible from Lisp is
    documented.)

This is not a bug.  We should leave this alone, drop the subject, and
focus our attention on fixing bugs.

Re: read-file-name-predicate

[Richard Stallman]

    `read-file-name-predicate' is a Lisp variable. It's doc says only that it is
    the current predicate used by built-in function `read-file-name-internal'.
    This is the only doc about it, and it gives the impression that it is only
    an internal variable for a built-in function. If that were true, then why
    would it be a Lisp variable instead of a C variable?

Sometimes a Lisp variable is more convenient.  For instance, it works
naturally with the specbind mechanism.

      `read-file-name-predicate' has an external,
    Lisp behavior: During completion, Lisp code can check what the predicate is
    or even change the predicate. Shouldn't that be documented?

I see no reason to document it at present.
It is meant for internal use only.

RE: read-file-name-predicate

[Drew Adams]

>     `read-file-name-predicate' has an external,
>     Lisp behavior: During completion, Lisp code can check what
>     the predicate is or even change the predicate. Shouldn't that
>     be documented?
>
> I see no reason to document it at present.
> It is meant for internal use only.

How is it different from `minibuffer-completion-predicate'? I see the two as
parallel.

Without this variable, how can you do, for file-name completion, what you
might do for non-file-name completion using
`minibuffer-completion-predicate'? Why document one but not the other?

Re: read-file-name-predicate

[Richard Stallman]

    Without this variable, how can you do, for file-name completion, what you
    might do for non-file-name completion using
    `minibuffer-completion-predicate'? Why document one but not the other?

Why not?

This is not important now.