RE: thing-at-point: inconsistent behaviour?

["Drew Adams" <drew.adams@oracle.com>]

>  > Especially since `thing-at-point' does NOT always return a string -
>  > it returns a list for (thing-at-point 'list), for instance.
> 
> On my GNU Emacs 24.1, `thing-at-point' always returns a (propertized) 
> string, including when used with 'list.

Yes, my bad about that one.  I think my point there was (or should have been)
that vanilla `thing-at-point' can return anything at all.  You cannot depend on
it to return a string or nil.

The version in `thingatpt+.el' ensures that the function returns a string or
nil, but the vanilla version does not.  This is because the vanilla version just
returns whatever the function that is the value of (get THING 'thing-at-point)
returns (if that property is non-nil).  It does not convert that (if non-nil) to
a string.

Since it is user-developers who put that property on THING symbols, they can use
whatever function they like, returning anything they like.

It is unfortunate that the terminology and function names suggest that any kind
of Lisp object (any THING) is returned by `thing-at-point', whereas its mission,
according to the doc (but not actually enforced) is to return only a string (or
nil).  It is really about giving you a buffer substring that _represents_ a Lisp
object (e.g. a list or a symbol).

It is all the more confusing because `thingatpt.el' also defines other
functions, such as `sexp-at-point', `symbol-at-point', `number-at-point', and
`list-at-point', which _do_ return Lisp objects.

It is further confusing because the function used to do that is `form-at-point'.
The Elisp manual gives "form" as "a Lisp object that is intended for
evaluation."

So user-developers should think to use `form-at-point' and not `thing-at-point'
if they want to return a Lisp object.  The difference is that `form-at-point'
reads the string returned by `thing-at-point', to obtain a Lisp object.

Function `thing-at-point' is about source-code representations of Lisp things.
Function `form-at-point' is about Lisp things.

And because it is so easy to just put a function on a symbol as property
`thing-at-point', users can wind up with perfectly workable calls to
`thing-at-point' which do just what they want but which do not, as the doc says,
return a string (or nil).

There are thus a few things to keep straight, starting with (1) the difference
between (thing-at-point 'symbol), which returns a symbol name and not a symbol
(likewise, for other THINGs - lists etc.), and ending with (2) the difference
between `thing-at-point' and `form-at-point' and (3) the caveat that
`thing-at-point' (a) is not intended to do what its name suggests (return a Lisp
THING) and (b) is not guaranteed to do what its doc says (return a string
representing a Lisp THING, or nil).