develooper Front page | perl.perl5.porters | Postings from October 2018

[perl #133499] Devel::Peek: misleading documentation forDump($hashref)

From:
James E Keenan via RT
Date:
October 14, 2018 01:25
Subject:
[perl #133499] Devel::Peek: misleading documentation forDump($hashref)
Message ID:
rt-4.0.24-23139-1539480311-62.133499-15-0@perl.org
On Fri, 07 Sep 2018 14:24:27 GMT, jkeenan wrote:
> On Thu, 06 Sep 2018 00:55:38 GMT, tonyc wrote:
> > On Tue, 04 Sep 2018 07:44:00 -0700, jkeenan@pobox.com wrote:
> > > Has the behavior of Devel::Peek changed since the
> > > documentation was written?  Or was the documentation simply
> > > wrong from the onset?
> >
> > No, the behaviour changed in
> > e1a7ec8d453649a65aea34af90c3042a5137191e.
> >
> > Note that you can get RITER/EITER if the HV is iterated over:
> >
> > $ ./perl -Ilib -MDevel::Peek -le '$a = { hello => 42 }; keys(%$a);
> > Dump($a)'
> > SV = IV(0x5639e6ab1a50) at 0x5639e6ab1a60
> >   REFCNT = 1
> >   FLAGS = (ROK)
> >   RV = 0x5639e6a8f508
> >   SV = PVHV(0x5639e6a95880) at 0x5639e6a8f508
> >     REFCNT = 1
> >     FLAGS = (OOK,SHAREKEYS)
> >     AUX_FLAGS = 0
> >     ARRAY = 0x5639e6aae330  (0:7, 1:1)
> >     hash quality = 100.0%
> >     KEYS = 1
> >     FILL = 1
> >     MAX = 7
> >     RITER = -1
> >     EITER = 0x0
> >     RAND = 0xeea6f6ff
> >     Elt "hello" HASH = 0x30ca77f3
> >     SV = IV(0x5639e6aa84a8) at 0x5639e6aa84b8
> >       REFCNT = 1
> >       FLAGS = (IOK,pIOK)
> >       IV = 42
> >
> > So perhaps the example could be updated.
> >
> 
> Tony, thanks for that explanation.  The updating could proceed in (at
> least) two directions:
> 
> 1. We could retain the code being dumped and omit (i) omit the RITER
> and EITER lines from the output; and (ii) the sentence, "Fields RITER
> and EITER are used by perlfunc/each."
> 

I decided to go with the simpler option: #1.  Pushed to blead in commit 7bf15fe2240f4090d85a676abda2b04456b58caa.


> 2. We could do (1) and then additionally document your example with
> 'keys'.  However, in that case we would not only have to explain the
> RITER and EITER lines; we would have to explain some additional lines
> as well.  This is what I get:
> 
> #####
> $ perl -MDevel::Peek -e '$a = { hello => 42 }; keys %{$a}; Dump $a;'
> SV = IV(0xeb0dc0) at 0xeb0dd0
>   REFCNT = 1
>   FLAGS = (ROK)
>   RV = 0xe8a578
>   SV = PVHV(0xe909c0) at 0xe8a578
>     REFCNT = 1
>     FLAGS = (OOK,SHAREKEYS)
>     AUX_FLAGS = 0
>     ARRAY = 0xeeb1d0  (0:7, 1:1)
>     hash quality = 100.0%
>     KEYS = 1
>     FILL = 1
>     MAX = 7
>     RITER = -1
>     EITER = 0x0
>     RAND = 0x9a8c1a4e
>     Elt "hello" HASH = 0xe2eb8e64
>     SV = IV(0xea5f58) at 0xea5f68
>       REFCNT = 1
>       FLAGS = (IOK,pIOK)
>       IV = 42
> #####
> 
> The FLAGS line now has:
> 
> #####
> FLAGS = (OOK,SHAREKEYS)
> #####
> 
> ... instead of just (SHAREKEYS).
> 
> This line is not previously documented:
> 
> #####
> AUX_FLAGS = 0
> #####
> 
> This line is also not previously documented:
> 
> #####
> RAND = 0x9a8c1a4e
> #####
> 
> Given that the behavior changed back in 2013, the documentation has
> been misleading for several years.  Hence, any change we make should
> be backportable to 5.26-maint and 5.28-maint.
> 
> Approach (1) above is easy; I could do it today.  But I don't know
> enough about hash structures to do approach (2).
> 
> How shall we proceed?
> 
> Thank you very much.

Thank you very much.

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

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=133499



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About