defcustom :type (file :must-match t)

defcustom :type (file :must-match t)

[Drew Adams]

I don't understand the customization type `(file :must-match t)'. The Elisp
manual says only this: "The value must be a file name for an existing file,
and you can do completion with `M-<TAB>'."

I don't see where/when/how this existence criterion is enforced.  At what
point is it checked and an error raised if you try to use a name that
corresponds to no file?

I am able to create a defcustom with a file name (with complete path) that
does not correspond to an existing file. I am able to customize the file
name in Customize, providing a name that doesn't correspond to an existing
file. I am able to set for the current session and even save such a nonsense
value.

So, in what sense _must_ the file-name value be the name of an existing
file? What am I missing?

The last phrase is, in any case, unclear: "and you can do completion with
`M-<TAB>'"? When/where can you do this? Does this mean in Customize, when
"you" are typing a new file name? With `set-variable' also? When "you" are
typing the defcustom? The Elisp manual is for programmers, and this section
of the manual tells "you" how to define a file-name :type, so I would guess
that the "you" here is not an end user of Customize but a programmer writing
a defcustom. But trial and error shows that "you" is the Customize end user,
and only Customize is meant, not also `set-variable'. This should be cleared
up.

If the only "must" check for existence is that provided by file-name
completion (e.g. REQUIRE-MATCH arg to `completing-read'), then this whole
entry should be rewritten to say that. Currently, it gives the impression
that `:type (file :must-match t)' will somehow, somewhere, somewhen, force
users to use file names that correspond to existing files.

Re: defcustom :type (file :must-match t)

[Luc Teirlinck]

Drew Adams wrote:

   I don't understand the customization type `(file :must-match t)'. The Elisp
   manual says only this: "The value must be a file name for an existing file,
   and you can do completion with `M-<TAB>'."

and:

   So, in what sense _must_ the file-name value be the name of an existing
   file? What am I missing?

In the sense that if Custom checks the type _in the minibuffer_ (as
opposed to in an editable field in a Custom buffer), say with
`customize-set-variable', the completion functions will prevent you
from entering a non-existent file name.  If you insist, you can enter
such a name anyway, with C-M-c (but that will usually be a bad idea).

This doc can be found in `(widget)atoms' (but I do not understand the
reference to the "tag button"; by default there seems to be no such
button):

 -- Widget: file
     Allows you to edit a file name in an editable field.  If you invoke
     the tag button, you can edit the file name in the mini-buffer with
     completion.

     Keywords:
    `:must-match'
          If this is set to non-`nil', only existing file names will be
          allowed in the minibuffer.


Sincerely,

Luc.

RE: defcustom :type (file :must-match t)

[Drew Adams]

       I don't understand the customization type `(file :must-match
       t)'. The Elisp manual says only this: "The value must be a
       file name for an existing file,
       and you can do completion with `M-<TAB>'."

       So, in what sense _must_ the file-name value be the name of
       an existing file? What am I missing?

    In the sense that if Custom checks the type _in the minibuffer_ (as
    opposed to in an editable field in a Custom buffer), say with
    `customize-set-variable', the completion functions will prevent you
    from entering a non-existent file name.  If you insist, you can enter
    such a name anyway, with C-M-c (but that will usually be a bad idea).

That is pretty weak enforcement. Most user modification will be in Customize
itself. Secondarily, I'd expect people might use `set-variable' more than
`customize-set-variable'. More importantly, :type is about controlling the
values users provide - regardless of how they input those values. Completion
against non-nil REQUIRE-MATCH in `completing-read' is hardly about :type
enforcement.

If this (completion) is the only way in which an existing file is checked,
then I would, at the least, clearly state that in the Elisp manual.

I'd also suggest that we either remove this :type altogether or (preferably)
look for a better way to enforce use of a file name that names an existing
file. The latter could be quite useful - we've never had anything like that
before.

Re: defcustom :type (file :must-match t)

[Luc Teirlinck]

According to its docstring the file widget is supposed to read a file
name value _in the minibuffer_.  Of course, we can all see that in
practice, it reads it in an editable field.  I do not know what is
going on.  From wid-edit.el:

(define-widget 'file 'string
  "A file widget.
It will read a file name from the minibuffer when invoked."
  :complete-function 'widget-file-complete
  :prompt-value 'widget-file-prompt-value
  :format "%{%t%}: %v"
  ;; Doesn't work well with terminating newline.
  ;; :value-face 'widget-single-line-field
  :tag "File")


Sincerely,

Luc.

Re: defcustom :type (file :must-match t)

[Luc Teirlinck]

>From my previous message:

   According to its docstring the file widget is supposed to read a file
   name value _in the minibuffer_.  Of course, we can all see that in
   practice, it reads it in an editable field.  I do not know what is
   going on.

By going through the Change Logs, I figured out that Richard changed
this eight and a half years ago, but the docstring (and some other
docs) apparently never got updated.  Since then, as I already
mentioned, :must-match only checks for actual existence of the file if
you manage to still invoke it through the minibuffer, say through
custom-set-variable.  The old code for invoking through the minibuffer
from a Custom buffer (widget-file-action) is still in wid-edit,
commented out.

Sincerely,

Luc.

Re: defcustom :type (file :must-match t)

[Luc Teirlinck]

>From my previous message:

   Since then, as I already mentioned, :must-match only checks for
   actual existence of the file if you manage to still invoke it
   through the minibuffer, say through custom-set-variable.

I meant customize-set-variable.

Sincerely,

Luc.

Re: defcustom :type (file :must-match t)

[Richard M. Stallman]

    According to its docstring the file widget is supposed to read a file
    name value _in the minibuffer_.  Of course, we can all see that in
    practice, it reads it in an editable field.  I do not know what is
    going on.  From wid-edit.el:

Please fix the doc string.

:must-match and set-variable (was: Re: defcustom :type (file :must-match t))

[Stuart D. Herring]

Luc wrote:
>                                          If you insist, you can enter
> such a name anyway, with C-M-c (but that will usually be a bad idea).

Hey, this is a neat answer to the recent discussion about set-variable --
it works just fine to set any variable by overriding the user-variable-p
check with C-M-c.  Perhaps add to set-variable's docs (or in the Emacs
Lisp manual or so) that that override may be useful to Lisp programmers?

Davis Herring

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

Re: defcustom :type (file :must-match t)

[Luc Teirlinck]

Richard Stallman wrote:

       According to its docstring the file widget is supposed to read a file
       name value _in the minibuffer_.  Of course, we can all see that in
       practice, it reads it in an editable field.  I do not know what is
       going on.  From wid-edit.el:

   Please fix the doc string.

I fixed the docstrings of the `file' and `directory' `define-widget's
in cus-edit.el and the description of the `file' widget in
man/widget.texi.  (The description of the directory widget in
man/widget.texi was already OK.)

Sincerely,

Luc.

Re: :must-match and set-variable

[Juri Linkov]

> Hey, this is a neat answer to the recent discussion about set-variable --
> it works just fine to set any variable by overriding the user-variable-p
> check with C-M-c.  Perhaps add to set-variable's docs (or in the Emacs
> Lisp manual or so) that that override may be useful to Lisp programmers?

Wouldn't it better to change `set-variable' to accept all variables or
create a new command than to document such an obscure way of doing that?

-- 
Juri Linkov
http://www.jurta.org/emacs/