Re: completing-read enhancement

[Paul Landes]

Stefan Monnier writes:
 > > To the developer, it offers a quicker way of prompting the user purely
 > > based on a list of choices (either symbols or strings) and.
 > 
 > > It adds the following features:
 > >  - accepts either symbols or string as input and converts between type
 > >    automatically
 > >  - returns user input as either a symbol or string
 > 
 > When/why are these useful?

For the former: anytime you want a discrete set of branches in a
function and don't want to convert using a lot of `intern' and
`symbol-name' calls.  You'd give a symbol list as the choices in the
interactive form and use a `case' on the decision.  This is just one
example and there many situations where the input is a list of symbols
rather than strings.  Similarly, there many cases where you want a
symbol output.

 > As a convention in Emacs, we usually prefer to start with an empty
 > input (and rely on the "use default if the result is the empty
 > string"), so I don't think this is something we want to encourage.

Is this a new convention?  Seems I've run across many functions that
allow it (including `completing-read').  What's the alternative to
when it's useful to start with text to edit rather than creating this
text from scratch?

This is tangential, but I've actually recently looked for a GNU Emacs
style guide but haven't found anything with the exception of the elisp
manual.  Is there one?  If so, I'd like to read up on this (and other
things concerning style).

 > >  - optionally allows for empty data
 > 
 > Could you say something more about this.  E.g. why you came up with it,
 > in which situations did you find it useful/needed, ...

Sure.  In any case where a valid choice is a `nil' and you want to
make that available by the least amount of effort by the user--namely
just hitting the RET key.  One example is when repeat input is
required and RET breaks out of the loop.  It's the "other" choice that
isn't valid in the constraints of the intended purpose of the input
and rather some indication in the change of flow.

 > > To the user, it provides a quicker (for most cases) way to select from
 > > the list of choices (i.e. by populating the initial data from the
 > > choices passed or by adding a default).
 > 
 > IIUC, the initial data is built by (try-completion "" choices), right?
 > It might make sense when require-match is set, but ho often does it
 > return something else than ""?

Now that I look at it, you're correct.  I seem to remember putting it
there to defend against cases where the initial-contents wasn't in the
list of the choices.  However, I've tested that case and it doesn't
help so it would make sense to take it out.

 > As for "adding default", I don't find in the code where/how this is done,
 > could you explain what you mean by that?

I meant adding the default parameter to the function.

 > One problem with your function is that it has even more arguments than
 > completing-read (which already has too many).

I agree, it has a lot of parameters that are passed to it, but no more
that are required than `completing-read'.  Only the first two are
required and most use cases won't require more than three or maybe
four.

 > PS: BTW, (try-completion "" choices) should also work just fine for the
 > singleton case.

I agree.  I could refactor the function to use this and make it
simpler.  It appears as that the entire `when' could use a little
looking at.  Please keep in mind that this function was written years
ago and has been incrementally maintained (by myself).  You're the
second pair of eyes on the code, and as expected, providing good
feedback to make it better.

Thanks.

-- 
Paul Landes
address@hidden