bug#22066: 24.5; documentation for "values" is not accurate

bug#22066: 24.5; documentation for "values" is not accurate

[Shiyao Ma]

[-- Attachment #1: Type: text/plain, Size: 3195 bytes --]

Hi,


the documentation of "values" (c-h v values) is not accurate.

(setq x 1) C-x C-e
values C-x C-e

In the above form, values is "nil". However, per the doc, "values"
should be (1).


On the other side, M-: does work.












In GNU Emacs 24.5.1 (x86_64-apple-darwin14.4.0, NS apple-appkit-1348.17)
 of 2015-08-11 on Mango
Configured using:
 `configure --prefix=/usr/local/Cellar/emacs/24.5
 --enable-locallisppath=/usr/local/share/emacs/site-lisp
 --infodir=/usr/local/Cellar/emacs/24.5/share/info/emacs --without-dbus
 --without-gnutls --with-ns --disable-ns-self-contained'

Important settings:
  value of $LC_ALL: en_US.UTF-8
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  elisp-slime-nav-mode: t
  eldoc-mode: t
  which-key-mode: t
  evil-jumper-mode: t
  evil-leader-mode: t
  evil-mode: t
  global-undo-tree-mode: t
  undo-tree-mode: t
  evil-local-mode: t
  override-global-mode: t
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:
ad-handle-definition: `evil-mode' got redefined
ad-handle-definition: `find-tag-noselect' got redefined
Loading term/xterm...done

Load-path shadows:
None found.

Features:
(shadow sort my-gnus gnus-util mail-extr emacsbug message format-spec
rfc822 mml mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils xterm elisp-slime-nav help-mode etags
eldoc my-conf my-lisp finder-inf time-date which-key my-evil evil-jumper
evil-leader evil evil-integration undo-tree diff evil-maps evil-commands
evil-command-window evil-types evil-search evil-ex evil-macros
evil-repeat evil-states evil-core byte-opt advice help-fns evil-common
windmove thingatpt rect evil-digraphs evil-vars ring my-graphics
use-package diminish bytecomp byte-compile cl-extra cconv bind-key
easy-mmode info easymenu package epg-config edmacro kmacro cl-loaddefs
cl-lib tooltip electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel ns-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list newcomment lisp-mode prog-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer nadvice loaddefs button
faces cus-face macroexp files text-properties overlay sha1 md5 base64
format env code-pages mule custom widget hashtable-print-readable
backquote make-network-process cocoa ns multi-tty emacs)

Memory information:
((conses 16 170015 106620)
 (symbols 48 25644 62)
 (miscs 40 32 174)
 (strings 32 36325 89256)
 (string-bytes 1 969614)
 (vectors 16 17041)
 (vector-slots 8 432858 68571)
 (floats 8 81 444)
 (intervals 56 198 78)
 (buffers 960 12))

[-- Attachment #2: Type: text/html, Size: 3635 bytes --]

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Shiyao Ma <i@introo.me> writes:

> the documentation of "values" (c-h v values) is not accurate.
>
> (setq x 1) C-x C-e
> values C-x C-e
>
> In the above form, values is "nil". However, per the doc, "values"
> should be (1).
>
> On the other side, M-: does work.

(I'm going through old bug reports that have unfortunately not gotten
any responses.)

---
values is a variable defined in ‘lread.c’.

[...]

List of values of all expressions which were read, evaluated and printed.
Order is reverse chronological.
---

Yes, that seems inaccurate.  It set in the readevalloop function, which
is probably what whoever wrote this meant to refer to, but that's not
very useful information.

But I'm not quite sure what the actual semantics are.  `eval-expression'
definitely sets it, but are there other functions that do?

`eval-last-sexp' doesn't, even when given a prefix (when it does read,
evaluate and print something).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> But I'm not quite sure what the actual semantics are.  `eval-expression'
> definitely sets it, but are there other functions that do?
>
> `eval-last-sexp' doesn't, even when given a prefix (when it does read,
> evaluate and print something).

I've looked a bit closed at what the semantics are, and they seem to be
pretty obscure.  Here's the only place where we put things on `values':

      if (printflag)
	{
	  Vvalues = Fcons (val, Vvalues);
	  if (EQ (Vstandard_output, Qt))
	    Fprin1 (val, Qnil);
	  else
	    Fprint (val, Qnil);
	}

printflag is an option in many functions, so if you say

(eval-region 2 13 t)

then the value will be stored in `values' -- otherwise not.  And this
has been this way since at least 1991 (which is the initial revision of
lread.c).

`eval-expression' has this:

  (if (null eval-expression-debug-on-error)
      (push (eval (let ((lexical-binding t)) (macroexpand-all exp)) t)
            values)

etc.  So it's being set a few places, and it's used in one single place:
`elisp--eval-defun'.

Anyway, I guess this means that `eval-last-sexp' is just missing a push?
So I've now added that to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Stefan Monnier]

FWIW, I think this `values` thingy should die.

It's just a memory leak plus one of the very few special-case variables
that are globally bound yet shouldn't be considered
a `special-variable-p` (The only other such cases I can remember are
`pi` (obsoleted by float-pi in 23.3) and `argv` and `argi` (both of
which should also be made obsolete, tho haven't yet either)).

IOW if we want to keep this feature, we should add some code to trim the
list and we should rename it so it doesn't need a special treatment.


        Stefan

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> FWIW, I think this `values` thingy should die.

I agree -- we could mark it obsolete now, but we'd have to rewrite the
one place where it's actually used:

(defun elisp--eval-defun ()
[...]
          (eval-region beg end standard-output
                       (lambda (_ignore)
                         ;; Skipping to the end of the specified region
                         ;; will make eval-region return.
                         (goto-char end)
                         form))))))
  (let ((str (eval-expression-print-format (car values))))
    (if str (princ str)))
  ;; The result of evaluation has been put onto VALUES.  So return it.
  (car values))

`eval-region' just returns nil, but that `lambda' could just capture the
value instead of the functoin then looking in `values', I think?  So the
one usage looks like it could be trivially rewritten.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Stefan Monnier]

> I agree -- we could mark it obsolete now, but we'd have to rewrite the
> one place where it's actually used:

Indeed, but it shouldn't be too hard.

> `eval-region' just returns nil, but that `lambda' could just capture the
> value instead of the functoin then looking in `values', I think?

The lambda is the read-function, so it doesn't receive the return value.
But we could just wrap the form inside
a `(setq elisp--eval-defun-result ,form)


        Stefan

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> `eval-region' just returns nil, but that `lambda' could just capture the
>> value instead of the functoin then looking in `values', I think?
>
> The lambda is the read-function, so it doesn't receive the return value.
> But we could just wrap the form inside
> a `(setq elisp--eval-defun-result ,form)

Yup.  I've now done this on the trunk, and I'm marking `values' as
obsolete (after doing some more testing).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Yup.  I've now done this on the trunk, and I'm marking `values' as
> obsolete (after doing some more testing).

Actually, I can't really mark `values' as obsolete, because that makes

(let (values)
  ...
  values)

issue a warning...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Stefan Monnier]

>> Yup.  I've now done this on the trunk, and I'm marking `values' as
>> obsolete (after doing some more testing).
> Actually, I can't really mark `values' as obsolete, because that makes
>
> (let (values)
>   ...
>   values)
>
> issue a warning...

The same problem affects `pi`.  For this reason it's declared obsolete
in NEWS and in its docstring but not with `make-obsolete` :-(

Maybe we should change the byte-compiler so it doesn't issue
obsolescence warnings when the variable is lexically scoped?

So we'd issue a warning for

    ... values ...

but not for

    (let ((values ...)) ... values ...)

?


        Stefan

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> The same problem affects `pi`.  For this reason it's declared obsolete
> in NEWS and in its docstring but not with `make-obsolete` :-(

Ah, I see.  I'll do the same with `values', then.

> Maybe we should change the byte-compiler so it doesn't issue
> obsolescence warnings when the variable is lexically scoped?
>
> So we'd issue a warning for
>
>     ... values ...
>
> but not for
>
>     (let ((values ...)) ... values ...)
>
> ?

Yes, that would be good.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Stefan Monnier]

>> So we'd issue a warning for
>>
>>     ... values ...
>>
>> but not for
>>
>>     (let ((values ...)) ... values ...)
>>
>> ?
>
> Yes, that would be good.

Actually, I see this is the case now.
So maybe we can actually declare them as `make-obsolete-variable` now.


        Stefan

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Actually, I see this is the case now.
> So maybe we can actually declare them as `make-obsolete-variable` now.

Ah, I wondered why there were so few of these warnings.  :-)

But there's about half a dozen functions in non-lexical files that use
the variable name `values'.  Uncomment the obsoletion of `values' and a
"make bootstrap" should show you them...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> Actually, I see this is the case now.
>> So maybe we can actually declare them as `make-obsolete-variable` now.
>
> Ah, I wondered why there were so few of these warnings.  :-)
>
> But there's about half a dozen functions in non-lexical files that use
> the variable name `values'.  Uncomment the obsoletion of `values' and a
> "make bootstrap" should show you them...

(But perhaps more seriously -- doing so will lead to spurious warnings
in non-lexical out-of-tree files...)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> But there's about half a dozen functions in non-lexical files that use
> the variable name `values'.  Uncomment the obsoletion of `values' and a
> "make bootstrap" should show you them...

Oh, I see you've found them already.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22066: 24.5; documentation for "values" is not accurate

[Stefan Monnier]

> (But perhaps more seriously -- doing so will lead to spurious warnings
> in non-lexical out-of-tree files...)

Might be worth a try, but we should probably first check the elpa.git
and nongnu.git packages, tho.


        Stefan