bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type

bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type

[MON KEY]

documentation of function `indirect-function' and `symbol-function' do
not adequately enumerate all of the types of return values (nor does
it even make mention of them) and docstring of `indirect-function' too
closeley mirrors that of `indirect-variable'.

Additionally, the value of its argument OBJECT does not reflect that
of the `symbol-function' arg SYMBOL it should because its return value
more closely resembles that of `symbol-function' than
`indirect-variable'.


,---- (documentation 'indirect-variable)
|
| Return the variable at the end of OBJECT's variable chain.
| If OBJECT is a symbol, follow all variable indirections and return the
| final variable.  If OBJECT is not a symbol, just return it.  Signal a
| cyclic-variable-indirection error if there is a loop in the variable
| chain of symbols.
|
| (fn OBJECT)
|
`----

,---- (documentation 'indirect-function)
|
| Return the function at the end of OBJECT's function chain.
| If OBJECT is not a symbol, just return it.  Otherwise, follow all
| function indirections to find the final function binding and return
| it.  If the final symbol in the chain is unbound, signal a
| void-function error.  Optional arg NOERROR non-nil means to return nil
| instead of signalling.  Signal a cyclic-function-indirection error if
| there is a loop in the function chain of symbols.
|
| (fn OBJECT &optional NOERROR)
|
`----

,---- (documentation 'symbol-function)
|
| Return SYMBOL's function definition.  Error if that is void.
|
| (fn SYMBOL)
|
`----

Given the similarity of docstrings for `indirect-variable' and
`indirect-function' it is possible for a user to assume the quoting
rules of `indirect-variable' apply as well to `indirect-function'.

In the following example `indirect-variable' returns regardless of
whether the arg OBJECT is quoted:

 (indirect-variable font-lock-comment-face)
 (indirect-variable 'font-lock-comment-face)

Whereas, in the following evaluation of `indirect-function'  the first
 use of an arg as unquoted symbol signals an error.

 (indirect-function lisp-mode-variables)
 (indirect-function 'lisp-mode-variables)

This problem isn't an issue were it not for the close resemblance of
the `indirect-function' `indirect-variable' docstrings.

More troublesome though is that neither `indirect-function' nor
`symbol-function' document their return values in any meaningful way:

Following is an attempt at fleshing out those return values not
specified by the existing docstrings (substitute OBJECT for SYMBOL
accordingly):

,----
|
| If OBJECT satisfies the predicate `subrp' return an unreadable
| object of the form:
|
|  #<subr SOME-SUBR-NAME>
|
| If OBJECT is an "autuload object" type its return value is a list of
| values suitable for use as arguments to the `autoload' function and
| of the form:
|
|  (autoload "<FILENAME>" <DOCSTRING-POSN> <INTERACTIVE> <TYPE>)
|
| Note, the <TYPE> element for OBJECT's return value as "autoload
| object" is nil for a function and `macro' or `t' for a macro.
|
| If value of OBJECT is a "byte-code function" type, e.g. it would
| satisfy the predicate `byte-code-function-p', and OBJECT is not a
| "Lisp macro" its value is returned as an unreadable vector of the
| form:
|
|  #[ ... ]
|
| if OBJECT is a "Lisp macro" in it value is returned as a cons of the
| form:
|
|  (macro . #[ ... ])
|
`----

--
/s_P\

bug#6497: 6497

[Geoff Gole]

> Given the similarity of docstrings for `indirect-variable' and
> `indirect-function' it is possible for a user to assume the quoting
> rules of `indirect-variable' apply as well to `indirect-function'.

There are no "quoting rules" for indirect-variable or
indirect-function. They are regular functions and have the same
argument evaluation semantics as every other regular function.

> More troublesome though is that neither `indirect-function' nor
> `symbol-function' document their return values in any meaningful way:

They mention that they return a "function definition", which is
appropriately abstract given that these functions don't depend in any
way on the details of function representation. Function values are
already documented in detail elsewhere, and duplicating that
documentation would not be helpful.

bug#6497: 6497

[MON KEY]

On Thu, Jul 1, 2010 at 5:20 AM, Geoff Gole <geoffgole@gmail.com> wrote:

> Given the similarity of docstrings for `indirect-variable' and
> `indirect-function' it is possible for a user to assume the quoting
> rules of `indirect-variable' apply as well to `indirect-function'.

>> There are no "quoting rules" for indirect-variable or

When given an unquoted symbol as its argument `indirect-variable' will
return the value of a non-null symbol. That it does so represents a
subtle alteration of the generally expected semantics e.g. wheras
`indirect-function' does signal an error.

>> indirect-function. They are regular functions and have the same
>> argument evaluation semantics as every other regular function.

Neither are regular lisp functions they are both primitives defined in
src/data.c

     (symbol-function 'indirect-function)
     (symbol-function 'indirect-variable)

> More troublesome though is that neither `indirect-function' nor
> `symbol-function' document their return values in any meaningful way:

>> They mention that they return a "function definition",
Except, that they don't always. which the docstring is in error.

>> which is appropriately abstract

Appropriately abstract for whom?

>> given that these functions don't depend in any way on the details
>> of function representation.

Sure they rely on the details of the function representation:

(symbol-function 'not-a-real-function)
 => (void-function not-a-real-function)

(symbol-functiol not-a-real-function)
=> (void-function symbol-functiol)

(symbol-function indirect-function)
=> (void-variable indirect-function)   ;; <-- void-variable

(indirect-function 'not-a-real-function)
=> (void-function not-a-real-function)

(indirect-function not-a-real-function)
=> (void-variable not-a-real-function) ;; <-- void-variable

(indirect-function symbol-function)
=> (void-variable symbol-function)     ;; <-- void-variable

How do these primitives reach determination that the function cell of
`not-a-real-function' is void if they don't access som portion of the
representation denoting that symbol is function/variable?

>> Function values are already documented in detail elsewhere, and

In detail and across a wide range. e.g.:

- See bug#6496 re autoload objects not appearing in "What is a
  function" node in manual.

- See bug#6486 re `byte-code-function-p' requiring the user to cross
  reference 3x info nodes in order to conclude that its return value
  is as per `symbol-function'.


>> duplicating that documentation would not be helpful.

Would not be helful for whom?

`symbol-function' and `indirect-function' are the cannonical
interfaces by which one can access the function cell of a symbol.

The docstring of `symbol-function' is a terse one sentence and doesn't
provide any indication that the _readability_ of its return value
varies significantly acording to the type of function given as the
arugment.

Really, symbol-function and his buddy `indirect-function' return:

 - a lambda form
 - a vector
 - a list
 - a cons
 - and two types of unreadable objects

I would suggest this is is abnormal compared w/ the vast majority of
Emacs lisp functions' return values.

--
/s_P\

bug#6497: 6497

[Geoff Gole]

> When given an unquoted symbol as its argument `indirect-variable' will
> return the value of a non-null symbol. That it does so represents a
> subtle alteration of the generally expected semantics

No it does not. The form (indirect-variable foo) is evaluated by
fetching the value of the symbol foo and passing it to the function
definition of indirect-variable, just like every other regular
function in emacs.

See (info "(elisp)Evaluation").

> Neither are regular lisp functions they are both primitives defined in
> src/data.c

Whether they are implemented in C or lisp is irrelevant. All regular
functions have their arguments evaluated in the same way.

> Except, that they don't always. which the docstring is in error.

I guess I phrased that poorly. These functions always return the
function definition, which is just a value and not guaranteed to be a
callable function at all. The "function definition" is simply whatever
lisp value happens to be in the function slot of said symbol:

(progn
  (fset foo 3)
  (symbol-function foo)) => 3

There is no restriction on the type of the value retrieved by
symbol-function whatsoever.

> Sure they rely on the details of the function representation:

No, see above.

> (symbol-function indirect-function)
> => (void-variable indirect-function)   ;; <-- void-variable

> (indirect-function not-a-real-function)
> => (void-variable not-a-real-function) ;; <-- void-variable

> (indirect-function symbol-function)
> => (void-variable symbol-function)     ;; <-- void-variable

These results are all straightforward, predictable results of the lisp
evaluation process. The only difficulty is that emacs lisp is a
lisp-2, with separate namespaces for values and functions. Once you
understand that evaluating the symbol 'symbol-function' fetches from
the *value slot* of that symbol, while the function definition
accessed by symbol-function (or by calling the function) resides in
the *function slot*, you'll see that this is the expected behaviour.

Again, see (info "(elisp)Evaluation").

> How do these primitives reach determination that the function cell of
> `not-a-real-function' is void if they don't access som portion of the
> representation denoting that symbol is function/variable?

The primitives in question know about the C representation of
*symbols*, in particular how to test whether a function slot is empty.
They do not know or care about the representation of functions.

Why don't you go and look at the C implementation of symbol-function
and indirect-function and verify for yourself what is going on?

> - See bug#6496 re autoload objects not appearing in "What is a
>  function" node in manual.
>
> - See bug#6486 re `byte-code-function-p' requiring the user to cross
>  reference 3x info nodes in order to conclude that its return value
>  is as per `symbol-function'.

Perhaps that documentation should be changed. Documentation bugs don't
seem to get much attention, though.

> `symbol-function' and `indirect-function' are the cannonical
> interfaces by which one can access the function cell of a symbol.

The documentation of symbol-function is fine. The function itself is a
simple accessor that does nothing except fetch a value from the
function slot of a symbol, and the docstring reflects that.

> Really, symbol-function and his buddy `indirect-function' return:
>
>  - a lambda form
>  - a vector
>  - a list
>  - a cons
>  - and two types of unreadable objects

They can return many more types of value than that. This is a natural
result of the fairly large Emacs Lisp type zoo and nothing to do with
the functions themselves.

bug#6497: 6497

[MON KEY]

>> When given an unquoted symbol as its argument `indirect-variable'
>> will return the value of a non-null symbol. That it does so
>> represents a subtle alteration of the generally expected semantics

> No it does not. The form (indirect-variable foo) is evaluated by
> fetching the value of the symbol foo and passing it to the function
> definition of indirect-variable, just like every other regular
> function in emacs.

Except it doesn't, as indicated by following pathology:

 (setq foo (unintern (makunbound 'foo)))
 (indirect-variable foo)

`foo' should evaluate to t per return value of `unintern'.

>> Neither are regular lisp functions they are both primitives defined in
>> src/data.c

> Whether they are implemented in C or lisp is irrelevant. All regular
> functions have their arguments evaluated in the same way.

If all regular functions have their arguments evaluated in the same
way it is tautological to identify them by virtue of their property of
regularity. Are you saying that unless a function is a
special-operator its arguments are evaluated in an identical manner as
any other non special-operator?

> callable function at all. The "function definition" is simply
> whatever lisp value happens to be in the function slot of said
> symbol:

> (progn
>  (fset foo 3)
>   (symbol-function foo)) => 3

The previous form is twice in error. Which FWIW, I fail to find
particularly humorous given the implied pedantry of your example.

Prob. what you meant to was:

(progn
 (fset 'foo 3)
 (symbol-function 'foo))
 ;=> 3

Which is all well and good except that,

(progn
 (unintern 'foo)
  (fset 'foo (indirect-function 'indirect-function))
  (symbol-function 'foo))
  ;=> #<subr indirect-function>

following should evaluate to `#<subr indirect-function>' but won't.

  (indirect-function 'foo)
  ;=> (void-function foo)

> There is no restriction on the type of the value retrieved by
> symbol-function whatsoever.

Sure there is, see error retrieved when fetching value of `foo' above.

> These results are all straightforward, predictable results of the
> lisp evaluation process. The only difficulty is that emacs lisp is a
> lisp-2, with separate namespaces for values and functions. Once you

You've missed my point. The distinction between value cell and
function cell confirms a reliance on the details of function
representation.  I was responding apropos your assertion:

,----
| given that these functions don't depend in any way on the details of
| function representation.
`----

> Why don't you go and look at the C implementation of symbol-function
> and indirect-function and verify for yourself what is going on?

I have, though one should not be required to examine src/lisp.h and
src/data.c in order to make sense of them and besides "what is going
on" inside data.c has little to do with the subject of this bug
report, e.g. deficient documentation _of_ the implementation and not
_the_ implementation itself.


--
/s_P\

bug#6497: 6497

[Geoff Gole]

> Prob. what you meant to was:
> (progn
>  (fset 'foo 3)
>  (symbol-function 'foo))

Indeed, although it's a trivial mistake. The example works just as
well when the value of foo is a symbol, which it must have been at the
time I tried it.

> <examples of unintern doing funny things>

Unintern does funny things. Those funny things are not relevant to
this bug report.

> The distinction between value cell and
> function cell confirms a reliance on the details of function
> representation.

What a bizarre claim. The number of slots in a symbol has nothing to
do with the representation of functions. Why would it?

bug#6497: 6497

[Andreas Schwab]

MON KEY <monkey@sandpframing.com> writes:

> Except it doesn't, as indicated by following pathology:
>
>  (setq foo (unintern (makunbound 'foo)))
>  (indirect-variable foo)
>
> `foo' should evaluate to t per return value of `unintern'.

The foos in the two lines are completely unrelated.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#6497: 6497

[MON KEY]

On Sat, Jul 3, 2010 at 3:00 AM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> MON KEY <monkey@sandpframing.com> writes:
>
>> Except it doesn't, as indicated by following pathology:
>>
>>  (setq foo (unintern (makunbound 'foo)))
>>  (indirect-variable foo)
>>
>> `foo' should evaluate to t per return value of `unintern'.
>
> The foos in the two lines are completely unrelated.
>

Yep.

The "first" foo is made unbound.
The "first" foo is uninterned which returns `t'.
The "second" foo is bound to the return value of uninterning the
"first" foo e.g. `t'.

That was not the point of the illustration.

This was:

The evaluation of the indirect-variable for the "second" foo should return `t'.

In the following, we change the "first" foo to a `tbar' there is no
"second" foo and we `set'  tbar instead of `setq'ing foo and this form
does return `t':

(unwind-protect
    (progn (unintern 'foo) (unintern 'tbar))
  (let ((tbar (make-symbol "foo") ))
    (set 'tbar (unintern (makunbound 'foo)))
    (indirect-variable tbar)))
; => t

> Andreas.

--
/s_P\

bug#6497: 6497

[MON KEY]

On Sat, Jul 3, 2010 at 2:31 AM, Geoff Gole <geoffgole@gmail.com> wrote:
>> Prob. what you meant to was:
>> (progn
>>  (fset 'foo 3)
>>  (symbol-function 'foo))
>
> Indeed, although it's a trivial mistake. The example works just as
> well when the value of foo is a symbol, which it must have been at the
> time I tried it.
>
The triviality of the mistake is apropos my rationale for requesting
that the docstrings be further fleshed out, it is all to easy to find
oneself in these sorts of situations w/re `symbol-function' &
`indirect-function' and no way to reasonably partition an expected
return value(s) from an unexpected one... That you fell pey to it
while trying to illustrate a counter argument to my proposal is (in
some small way) an indicative of the problem.

> Unintern does funny things. Those funny things are not relevant to
> this bug report.

See above.

>
>> The distinction between value cell and
>> function cell confirms a reliance on the details of function
>> representation.
>
> What a bizarre claim. The number of slots in a symbol has nothing to
> do with the representation of functions. Why would it?
>

If the symbol did not have cells it would. Which the "bizarre"
behaviour of the unintern/makunbound examples illustrate.

--
/s_P\

bug#6497: 6497

[Andreas Schwab]

MON KEY <monkey@sandpframing.com> writes:

> The "second" foo is bound to the return value of uninterning the
> "first" foo e.g. `t'.

This is still the first foo.

> The evaluation of the indirect-variable for the "second" foo should return `t'.

This foo has no value.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type

[Glenn Morris]

I don't see a need to keep open this particular report.