bug#32064: 26; doc string of `eval-last-sexp'

bug#32064: 26; doc string of `eval-last-sexp'

[Drew Adams]

The doc string was messed up a bit in Emacs 26, apparently for the fix
of bug #4118.

From this, which makes sense:

 Normally, this function truncates long output according to the value
 of the variables `eval-expression-print-length' and
 `eval-expression-print-level'.  With a prefix argument of zero,
 however, there is no such truncation.  Such a prefix argument
 also causes integers to be printed in several additional formats
 (octal, hexadecimal, and character).

The text was changed to this, which does not make sense at all:

 Normally, this function truncates long output according to the
 value of the variables 'eval-expression-print-length' and
 'eval-expression-print-level'.  With a prefix argument of zero,
 however, there is no such truncation.  Such a prefix argument
 also causes integers to be printed in several additional formats
 (octal, hexadecimal, and character when the prefix argument is
 -1 or the integer is 'eval-expression-print-maximum-character' or
 less).

Both old and new say that with a prefix arg of ZERO ("such a prefix
argument") the behavior is to do both of these things:

1. Do not truncate.
2. Print in additional formats.

That's fine. But the Emacs 26+ version also says that with a ZERO prefix
arg ("such a prefix argument"), if the prefix arg is ALSO -1
(impossible) or if "the integer" (what integer?) is less than or equal
to the value of `eval-expression-print-maximum-character', the
additional formats include "character".

A character is not a format, so it's unclear what printing in format
"character" means.

But the main problem with this is that it makes us try to understand a
prefix arg that is BOTH zero and -1, and it leaves us wondering what
"the integer" is that is tested against
`eval-expression-print-maximum-character' when the prefix arg is zero.

If "the integer" is just the numeric prefix arg then the <=
`eval-expression-print-maximum-character' could be clear - but there
should be no connection with the value being zero ("such a prefix arg").
Just say: If zero then no truncation.  If <= `eval...' then ___
(whatever is meant by "character format" printing).


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#32064: 26; doc string of `eval-last-sexp'

[Drew Adams]

Looking at `eval-expression-get-print-arguments' and the doc string for `eval-expression', things are a bit clearer.  At least please incorporate something like what is said for `eval-expression' in the doc of `eval-last-sexp'. 

But even the `eval-expression' doc is not very good for the description of CHAR-PRINT-LIMIT.  It's not true that "unless given a positive prefix argument" a number value is printed in several... Try a prefix arg of -9, for instance.

The doc of `eval-expression-get-print-arguments' says that it determines the prefix-arg behavior for `eval-last-sexp'.  Is that true?

The doc of `eval-expression-get-print-arguments' needs to specify the logic of what it does, and that info needs to be included in the doc of `eval-expression' and (if appropriate) the doc of `eval-last-sexp'.  Or at least their doc needs to point to such info.

The doc string for `eval-expression-print-format' is not great either.  It says only what the result will "typically" look like.  It needs to specify what formats it outputs, under what conditions.

It seems that this is the situation for `eval-expression-get-print-arguments':

No prefix arg : no insert,    truncate, 127
-             : no insert,    truncate, 127
0             :    insert, no truncate, 127
-1            :    insert,    truncate, biggest fixnum
else          :    insert,    truncate, nil

Is that right?  If so, the doc should spell that out.
There's no way a user will guess this or get it easily
from the current doc.

And the various doc strings seem to suggest that the handling of the last arg, CHAR-PRINT-LIMIT by `eval-exprresion' is different from its handling by `eval-last-sexp'.  But is that true?

This is all a confusing mess, I'm afraid.  And the code (e.g. of `eval-last-sexp' and its helper `elisp--eval-last-sexp') is not very clear either.

bug#32064: 26; doc string of `eval-last-sexp'

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

> This is all a confusing mess, I'm afraid.  And the code (e.g. of
> `eval-last-sexp' and its helper `elisp--eval-last-sexp') is not very
> clear either.

I agree.  I think the solution is to simplify the interface somewhat.
As it stands, we're trying to cram a lot of functionality into the
prefix argument, and the encoding is too difficult to remember (both in
terms of implementing & documenting, as well as for using).

Instead, we should have something like this:

No prefix: echo with default formatting (like now)
C-u: insert result into buffer, no alternate integer formatting (like now)
C-u C-u: query user for detailed formatting options individually

And that's it, no clever handling of 0 vs negative number vs `-', etc

bug#32064: 26; doc string of `eval-last-sexp'

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Thu, 05 Jul 2018 20:23:08 -0400
> Cc: 32064@debbugs.gnu.org
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
> > This is all a confusing mess, I'm afraid.  And the code (e.g. of
> > `eval-last-sexp' and its helper `elisp--eval-last-sexp') is not very
> > clear either.
> 
> I agree.  I think the solution is to simplify the interface somewhat.

These additional features weer added just recently, so I see no reason
why we should remove them now.  Certainly not because the doc string
needs to be fixed.

> As it stands, we're trying to cram a lot of functionality into the
> prefix argument, and the encoding is too difficult to remember (both in
> terms of implementing & documenting, as well as for using).

I had no difficulty bringing the doc string in line with the
implementation, please take a look.

bug#32064: 26; doc string of `eval-last-sexp'

[Noam Postavsky]

Eli Zaretskii <eliz@gnu.org> writes:

>> I agree.  I think the solution is to simplify the interface somewhat.
>
> These additional features weer added just recently, so I see no reason
> why we should remove them now.  Certainly not because the doc string
> needs to be fixed.

>> As it stands, we're trying to cram a lot of functionality into the
>> prefix argument, and the encoding is too difficult to remember (both in
>> terms of implementing & documenting, as well as for using).
>
> I had no difficulty bringing the doc string in line with the
> implementation, please take a look.

Thanks, I think that fixes all the typos and mistaken descriptions.  I
am still of the opinion that the prefix args apart from C-u are too
complicated to be of much use.  But we can wait a bit longer and maybe
the next formatting feature will be the straw that breaks the proverbial
camel's back.

bug#32064: 26; doc string of `eval-last-sexp'

[Drew Adams]

> >> I agree.  I think the solution is to simplify the interface somewhat.
> >
> > These additional features weer added just recently, so I see no reason
> > why we should remove them now.  Certainly not because the doc string
> > needs to be fixed.
> 
> >> As it stands, we're trying to cram a lot of functionality into the
> >> prefix argument, and the encoding is too difficult to remember (both
> >> in terms of implementing & documenting, as well as for using).
> >
> > I had no difficulty bringing the doc string in line with the
> > implementation, please take a look.
> 
> Thanks, I think that fixes all the typos and mistaken descriptions.  I
> am still of the opinion that the prefix args apart from C-u are too
> complicated to be of much use.  But we can wait a bit longer and maybe
> the next formatting feature will be the straw that breaks the proverbial
> camel's back.

Thanks for the doc string corrections.

I agree with Noam that the behavior is not great.  It's not
very user-friendly or very useful.  It should be rethought,
even at the cost of backward incompatibility.  Perhaps a
new, replacement command should be added and given the
key binding, keeping the old command available for whoever
wants to restore its binding.

I started to write a mail to emacs-devel about this
yesterday, but I dropped it, at least for now.

FWIW, I think it would be good if the various Lisp
evaluation commands acted more or less similarly - e.g.,
wrt a prefix arg.  There are several, including:

`eval-last-sexp', `eval-print-last-sexp',
`pp-eval-last-sexp', `eval-expression',
`pp-eval-expression', `eval-region',
`eval-defun', `eval-buffer', and
`lisp-eval-defun'

Something I've been thinking about is the need I have
to evaluate Lisp code with `lexical-binding' optionally
non-nil.

I know that the expectation of some (maybe all) is that
Emacs will eventually make non-nil the default value of
`lexical-binding', or even remove the variable altogether
and make binding lexical by default (the same effect as
having the variable default to non-nil everywhere, but
with no ability to change the behavior to what nil gives).

FWIW, I have no problem with that, as long as dynamic
binding is still available - exactly the situation of
Common Lisp, and _not_ the situation of Scheme.

Still, it is now, and it can remain in the future, useful
to be able to grab a bit of code from anywhere and
evaluate it optionally with `lexical-binding' in effect.

I sometimes copy Lisp code from files I'm working on to
another Lisp buffer, to modify and experiment with.  The
buffer I copy it to might serve for code that comes from
buffers with nil and non-nil `lexical-binding'.

And it might not be a file buffer, or I might not have
bothered to add a local-variable declaration for it.
E.g. `C-x 4 f foo.el', for a non-existent file `foo.el',
does not default to non-nil `lexical-binding' (yes, I
could make it do that).

When I want to evaluate bits of code in such a test
buffer, it won't do to just use `eval-region' or
`eval-expression' or `eval-last-sexp'.  Depending on
whether the code to be eval'd _depends on_ lexical
binding, I need to first set `lexical-binding' as
needed, perhaps temporarily, for the whole buffer.

I'd prefer to have the evaluation commands take care
of this.  I can of course define separate commands for
lexical binding, like so:

(defun eval-region-lexical (start end &optional printflag
                            read-function)
  "..."
  (interactive "r")
  (let ((lexical-binding  t))
    (eval-region start end printflag read-function)))

But it would be handy if the regular commands would let
me provide a prefix arg to get that behavior.  E.g.:

(defun eval-region (start end &optional printflag
                    read-function lexicalp)
  "..."
  (interactive "r\ni\ni\nP")
  (let ((lexical-binding  (if lexicalp t lexical-binding)))
    (eval-region start end printflag read-function)))

That would work for `eval-region', because it currently
defines no prefix-arg behavior.

But for the other eval commands things are less simple.
They already use prefix args to the max (too much).  Like
Noam, I'd argue that the prefix arg behavior for some of
them is far too complex, if not tricky.  The resulting doc
is consequently pretty much a mess.

Can we come up with something better?  Maybe there needs
to be more than one command for some of these things that
are currently combined via prefix args (again, something
that Noam too suggested)?  Or maybe some better
combinations can be found?

You'll note that I included the `pp-eval-*' commands in
the list above.  I bind (a variant of) `pp-eval-expression'
to `M-:', for instance.  I'd like `pp-eval-*' commands to
also share in a reflection about better and more consistent
prefix-arg behavior.

---

FWIW, my variant of `pp-eval-expression' does the following.
I mention it for the info about prefix-arg behavior.  IOW,
I realize that different eval commands can have different
uses for a prefix arg.  Still, some more consistency, and
less complexity, than now would help.

- Read with completion, using `pp-read-expression-map',
  which is like `read-expression-map' but with some
  Emacs-Lisp key bindings.

- Respect option `eval-expression-debug-on-error'.

- With no prefix arg, respect option `pp-max-tooltip-size'.
  If a tooltip is not used then if the value fits on one
  line (frame width) show it in the echo area.  Otherwise,
  show it in buffer *Pp Eval Output*'.

- With a zero prefix arg, swap the use of a tooltip
  according to `pp-max-tooltip-size': if that option is
  `nil' then use a tooltip; if non-`nil' then do not use
  a tooltip.

- With non-zero prefix arg, insert the value into the
  current buffer at point. With a negative prefix arg, if
  the value is a string then insert it without enclosing
  double-quotes (").

bug#32064: 26; doc string of `eval-last-sexp'

[Eli Zaretskii]

> Date: Thu, 5 Jul 2018 14:56:48 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Looking at `eval-expression-get-print-arguments' and the doc string for `eval-expression', things are a bit clearer.  At least please incorporate something like what is said for `eval-expression' in the doc of `eval-last-sexp'. 

I preferred to fix eval-last-sexp in a somewhat different way.

> But even the `eval-expression' doc is not very good for the description of CHAR-PRINT-LIMIT.  It's not true that "unless given a positive prefix argument" a number value is printed in several... Try a prefix arg of -9, for instance.

Right, fixed.

> The doc of `eval-expression-get-print-arguments' says that it determines the prefix-arg behavior for `eval-last-sexp'.  Is that true?

Yes, AFAICT.

> The doc of `eval-expression-get-print-arguments' needs to specify the logic of what it does, and that info needs to be included in the doc of `eval-expression' and (if appropriate) the doc of `eval-last-sexp'.  Or at least their doc needs to point to such info.

I see no reason to point to eval-expression-get-print-arguments in the
doc string of eval-last-sexp.  If someone reads the code of
eval-last-sexp, they will see the call, and will look up the function.

> The doc string for `eval-expression-print-format' is not great either.  It says only what the result will "typically" look like.  It needs to specify what formats it outputs, under what conditions.

I don't see the need, as the code is quite self-describing.

> And the various doc strings seem to suggest that the handling of the last arg, CHAR-PRINT-LIMIT by `eval-exprresion' is different from its handling by `eval-last-sexp'.  But is that true?

No, it is not true.  Fixed.

I'm closing the bug, thanks for pointing out these blunders.

bug#32064: 26; doc string of `eval-last-sexp'

[Eli Zaretskii]

> Date: Thu, 5 Jul 2018 13:15:16 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The doc string was messed up a bit in Emacs 26, apparently for the fix
> of bug #4118.

It was also somewhat messed up in Emacs 25.

> 1. Do not truncate.
> 2. Print in additional formats.
> 
> That's fine. But the Emacs 26+ version also says that with a ZERO prefix
> arg ("such a prefix argument"), if the prefix arg is ALSO -1
> (impossible) or if "the integer" (what integer?) is less than or equal
> to the value of `eval-expression-print-maximum-character', the
> additional formats include "character".
> 
> A character is not a format, so it's unclear what printing in format
> "character" means.
> 
> But the main problem with this is that it makes us try to understand a
> prefix arg that is BOTH zero and -1, and it leaves us wondering what
> "the integer" is that is tested against
> `eval-expression-print-maximum-character' when the prefix arg is zero.
> 
> If "the integer" is just the numeric prefix arg then the <=
> `eval-expression-print-maximum-character' could be clear - but there
> should be no connection with the value being zero ("such a prefix arg").
> Just say: If zero then no truncation.  If <= `eval...' then ___
> (whatever is meant by "character format" printing).

Thanks, I fixed the doc string on the emacs-26 branch to be both clear
and correct.