perlvar $@ could be improved

[p5pRT]

Migrated from rt.perl.org#124034 (status was 'resolved')

Searchable as RT124034$

[p5pRT]

From @mauke

Created by @mauke

$ perldoc -v '$@​'
  $EVAL_ERROR
  $@​ The Perl syntax error message from the last "eval()" operator. If
  $@​ is the null string, the last "eval()" parsed and executed
  correctly (although the operations you invoked may have failed in
  the normal fashion).

  ...

This description somewhat misses the point.

- it implies $@​ is only set by eval STRING and for compiler errors ("syntax
  error", "parsed and executed correctly")
- $@​ is not necessarily a "message" (i.e. a string)
- doesn't mention the common use as a generic exception mechanism via die/eval
  BLOCK
- What is "failed in the normal fashion"? Nowadays the normal fashion is often
  to throw an exception.
- I like "empty string" better than "null string"

Perl Info

Flags:
    category=docs
    severity=low

Site configuration information for perl 5.20.2:

Configured by mauke at Fri Feb 20 22:08:22 CET 2015.

Summary of my perl5 (revision 5 version 20 subversion 2) configuration:
   
  Platform:
    osname=linux, osvers=3.18.3-1-arch, archname=i686-linux
    uname='linux simplicio 3.18.3-1-arch #1 smp preempt sun jan 18 17:33:37 cet 2015 i686 gnulinux '
    config_args=''
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=undef, usemultiplicity=undef
    use64bitint=undef, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-O2',
    cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
    ccversion='', gccversion='4.9.2 20150204 (prerelease)', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=4, prototype=define
  Linker and Libraries:
    ld='cc', ldflags ='-fstack-protector -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/gcc/i686-pc-linux-gnu/4.9.2/include-fixed /usr/lib /lib
    libs=-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc -lgdbm_compat
    perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
    libc=libc-2.21.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.21'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
    cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector'



@INC for perl 5.20.2:
    /home/mauke/usr/lib/perl5/site_perl/5.20.2/i686-linux
    /home/mauke/usr/lib/perl5/site_perl/5.20.2
    /home/mauke/usr/lib/perl5/5.20.2/i686-linux
    /home/mauke/usr/lib/perl5/5.20.2
    .


Environment for perl 5.20.2:
    HOME=/home/mauke
    LANG=en_US.UTF-8
    LANGUAGE (unset)
    LC_COLLATE=POSIX
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/mauke/perl5/perlbrew/bin:/home/mauke/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl
    PERLBREW_BASHRC_VERSION=0.69
    PERLBREW_HOME=/home/mauke/.perlbrew
    PERLBREW_ROOT=/home/mauke/perl5/perlbrew
    PERL_BADLANG (unset)
    SHELL=/bin/bash

[p5pRT]

From @jkeenan

On Mon Mar 09 22​:46​:38 2015, mauke- wrote​:

This is a bug report for perl from l.mai@​web.de,
generated with the help of perlbug 1.40 running under perl 5.20.2.

-----------------------------------------------------------------
[Please describe your issue here]

$ perldoc -v '$@​'
$EVAL_ERROR
$@​ The Perl syntax error message from the last "eval()"
operator. If
$@​ is the null string, the last "eval()" parsed and
executed
correctly (although the operations you invoked may have
failed in
the normal fashion).

...

This description somewhat misses the point.

- it implies $@​ is only set by eval STRING and for compiler errors
("syntax
error", "parsed and executed correctly")
- $@​ is not necessarily a "message" (i.e. a string)
- doesn't mention the common use as a generic exception mechanism via
die/eval
BLOCK
- What is "failed in the normal fashion"? Nowadays the normal fashion
is often
to throw an exception.
- I like "empty string" better than "null string"

I agree with at least your last bullet point. Could you provide a patch with alternative working for people to chew over?

Thank you very much.
--
James E Keenan (jkeenan@​cpan.org)

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @jkeenan

On Mon Apr 27 18​:08​:19 2015, jkeenan wrote​:

On Mon Mar 09 22​:46​:38 2015, mauke- wrote​:

This is a bug report for perl from l.mai@​web.de,
generated with the help of perlbug 1.40 running under perl 5.20.2.

-----------------------------------------------------------------
[Please describe your issue here]

$ perldoc -v '$@​'
$EVAL_ERROR
$@​ The Perl syntax error message from the last "eval()"
operator. If
$@​ is the null string, the last "eval()" parsed and
executed
correctly (although the operations you invoked may have
failed in
the normal fashion).

...

This description somewhat misses the point.

- it implies $@​ is only set by eval STRING and for compiler errors
("syntax
error", "parsed and executed correctly")
- $@​ is not necessarily a "message" (i.e. a string)
- doesn't mention the common use as a generic exception mechanism via
die/eval
BLOCK
- What is "failed in the normal fashion"? Nowadays the normal fashion
is often
to throw an exception.
- I like "empty string" better than "null string"

I agree with at least your last bullet point. Could you provide a
patch with alternative working for people to chew over?

Thank you very much.

mauke​: Any possibility of getting a patch?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

[p5pRT]

From @mauke

On Wed Dec 09 15​:58​:31 2015, jkeenan wrote​:

mauke​: Any possibility of getting a patch?

Yes, thanks for the reminder. See the attachment.

Comments?

[p5pRT]

From @mauke

0001-reword-documentation-it-s-not-just-for-syntax-errors.patch

From a37623716b4aae990e70fa50b5130237d5b0faa2 Mon Sep 17 00:00:00 2001
From: Lukas Mai <l.mai@web.de>
Date: Thu, 10 Dec 2015 01:20:47 +0100
Subject: [PATCH] reword $@ documentation (it's not just for syntax errors)

RT #124034
---
 pod/perlvar.pod | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index f5922ad..09ec06d 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1667,12 +1667,12 @@ Under a few operating systems, C<$^E> may contain a more verbose error
 indicator, such as in this case, "CDROM tray not closed."  Systems that
 do not support extended error messages leave C<$^E> the same as C<$!>.
 
-Finally, C<$?> may be set to non-0 value if the external program
+Finally, C<$?> may be set to a non-0 value if the external program
 F</cdrom/install> fails.  The upper eight bits reflect specific error
 conditions encountered by the program (the program's C<exit()> value).
 The lower eight bits reflect mode of failure, like signal death and
 core dump information.  See L<wait(2)> for details.  In contrast to
-C<$!> and C<$^E>, which are set only if error condition is detected,
+C<$!> and C<$^E>, which are set only if an error condition is detected,
 the variable C<$?> is set on each C<wait> or pipe C<close>,
 overwriting the old value.  This is more like C<$@>, which on every
 C<eval()> is always set on failure and cleared on success.
@@ -1867,17 +1867,18 @@ Mnemonic: similar to B<sh> and B<ksh>.
 =item $@
 X<$@> X<$EVAL_ERROR>
 
-The Perl syntax error message from the
-last C<eval()> operator.  If C<$@> is
-the null string, the last C<eval()> parsed and executed correctly
-(although the operations you invoked may have failed in the normal
-fashion).
+The Perl error from the last C<eval> operator, i.e. the last exception that
+was caught.  For C<eval BLOCK>, this is either a runtime error message or the
+string or reference C<die> was called with.  The C<eval STRING> form also
+catches syntax errors and other compile time exceptions.
+
+If no error occurs, C<eval> sets C<$@> to the empty string.
 
 Warning messages are not collected in this variable.  You can, however,
 set up a routine to process warnings by setting C<$SIG{__WARN__}> as
 described in L</%SIG>.
 
-Mnemonic: Where was the syntax error "at"?
+Mnemonic: Where was the error "at"?
 
 =back
 
-- 
2.6.3

[p5pRT]

From @jkeenan

On Wed Dec 09 17​:14​:16 2015, mauke- wrote​:

On Wed Dec 09 15​:58​:31 2015, jkeenan wrote​:

mauke​: Any possibility of getting a patch?

Yes, thanks for the reminder. See the attachment.

Comments?

Thanks, applied to blead in commit 2e6ba11.
--
James E Keenan (jkeenan@​cpan.org)

[p5pRT]

@jkeenan - Status changed from 'open' to 'resolved'