search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.85k stars 527 forks source link

UNIVERSAL documentation contradicts itself #6464

Closed p5pRT closed 21 years ago

p5pRT commented 21 years ago

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

Searchable as RT22018$

p5pRT commented 21 years ago

From pcg@goof.com

Created by root@cerebro.laendle

SYNOPSIS says​:

  use UNIVERSAL qw( isa can VERSION );

DESCRIPTION says​:

  These subroutines should not be imported via "use UNIVERSAL   qw(...)". If you want simple local access to them you can do

If an import shouldn't be used then it should be said why\, and if imports can be used this paragraph should be dropped (I guess it wasn't implemented but now is).

Perl Info ``` Flags: category=docs severity=low Site configuration information for perl v5.8.1: Configured by root at Sat Mar 22 16:16:52 CET 2003. Summary of my perl5 (revision 5.0 version 8 subversion 1 patch 19045) configuration: Platform: osname=linux, osvers=2.4, archname=i686-linux uname='linux cerebro 2.4.18-pre8-ac3 #2 smp tue feb 5 17:35:23 cet 2002 i686 unknown ' config_args='' hint=previous, useposix=true, d_sigaction=define usethreads=undef use5005threads=undef useithreads=undef usemultiplicity=undef useperlio=define d_sfio=undef uselargefiles=define usesocks=undef use64bitint=undef use64bitall=undef uselongdouble=undef usemymalloc=y, bincompat5005=undef Compiler: cc='gcc', ccflags ='-I/opt/include -D_GNU_SOURCE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64', optimize='-Os -funroll-loops -mcpu=pentium -march=pentium -g', cppflags='-I/opt/include -D_GNU_SOURCE -I/opt/include -D_GNU_SOURCE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -I/opt/include -D_GNU_SOURCE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64' ccversion='', gccversion='3.2.3 20030316 (Debian 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='gcc', ldflags ='' libpth=/usr/lib /opt/lib libs=-lcrypt -ldl -lm -lc perllibs=-lcrypt -ldl -lm -lc libc=/lib/libc-2.2.5.so, so=so, useshrplib=false, libperl=libperl.a gnulibc_version='2.3.2' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-rdynamic' cccdlflags='-fpic', lddlflags='-shared' Locally applied patches: MAINT19040 @INC for perl v5.8.1: /root/src/sex /opt/perl/lib/perl5 /opt/perl/lib/perl5 /opt/perl/lib/perl5 /opt/perl/lib/perl5 . Environment for perl v5.8.1: HOME=/root LANG (unset) LANGUAGE (unset) LC_CTYPE=de_DE@euro LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/root/s2:/root/s:/opt/qt/bin:/opt/bin:/opt/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11/bin:/usr/games:/usr/local/bin:/usr/local/sbin:.:/root/cc/dejagnu/bin PERL5LIB=/root/src/sex PERL5_CPANPLUS_CONFIG=/root/.cpanplus/config PERLDB_OPTS=ornaments=0 PERL_BADLANG (unset) SHELL=/bin/bash ```
p5pRT commented 21 years ago

arthur@contiller.se - Status changed from 'new' to 'open'

p5pRT commented 21 years ago

From @cwest

It was Tuesday\, April 22\, 2003 when Marc Lehmann took the soap box\, saying​: : ----------------------------------------------------------------- : [Please enter your report here] : : SYNOPSIS says​: : : use UNIVERSAL qw( isa can VERSION ); : : DESCRIPTION says​: : : These subroutines should not be imported via "use UNIVERSAL : qw(...)". If you want simple local access to them you can do : : If an import shouldn't be used then it should be said why\, and if : imports can be used this paragraph should be dropped (I guess it wasn't : implemented but now is).

Your guess is correct. This patch cleans up the documentation to explain the import rules.

  Casey West

-- "I loathe people who keep dogs. They are cowards who haven't got the guts to bite people themselves." --August Strindberg

Inline Patch ```diff --- perl-current.orig/lib/UNIVERSAL.pm Mon Apr 21 10:50:06 2003 +++ perl-current/lib/UNIVERSAL.pm Wed Apr 23 09:53:32 2003 @@ -108,11 +108,10 @@ =back -These subroutines should I be imported via S>. -If you want simple local access to them you can do +=head1 EXPORTS - *isa = \&UNIVERSAL::isa; +None by default. -to import isa into your package. +You may request the import of all three functions C, C, and C. =cut ```
p5pRT commented 21 years ago

From @cwest

It was Wednesday\, April 23\, 2003 when Robin Barker took the soap box\, saying​: : There are also some collision of C\<> and -> in the UNIVERSAL.pm pod. : The attached patch cleans up this and some other bits of the pod. : My patch should be applied as well as (not instead of) Casey's.

As well\, I forgot to address the question of 'if those functions should not be imported\, the documentation should say why'. So to your patch and my previous I add the patch below my signature.

Also\, your patch was a bit hard to apply because it seems that your mailer played wrapping games on it. I've attached a cleaned up copy of your patch.

  Casey West

-- I am a superhero.

Inline Patch ```diff --- perl-current.orig/lib/UNIVERSAL.pm Wed Apr 23 10:24:44 2003 +++ perl-current/lib/UNIVERSAL.pm Wed Apr 23 10:25:51 2003 @@ -138,6 +138,8 @@ None by default. -You may request the import of all three functions C, C, and C. +You may request the import of all three functions (C, C, and +C), however it isn't necessary to do so. Perl magically makes these +functions act as methods on all objects. =cut ```
p5pRT commented 21 years ago

From @cwest

uni.diff ```diff --- ../perl@19401/lib/UNIVERSAL.pm Thu Jan 23 14:22:55 2003 +++ lib/UNIVERSAL.pm @@ -41,20 +41,42 @@ =over 4 -=item $obj->isa( TYPE ), CLASS->isa( TYPE ), isa( VAL, TYPE ) +=item C<< $obj->isa( TYPE ) >> - C is a package name - $obj is a blessed reference or a string containing a package name - C is a package name - C is any of the above or an unblessed reference - -When used as an instance or class method (C<$obj->isa( TYPE )>), C -returns I if $obj is blessed into package C or inherits from -package C. - -When used as a class method (Cisa( TYPE )>; sometimes referred to as a -static method), C returns I if C inherits from (or is itself) -the name of the package C or inherits from package C. +=item C<< CLASS->isa( TYPE ) >> + +=item C + +Where + +=over 4 + +=item C + +is a package name + +=item C<$obj> + +is a blessed reference or a string containing a package name + +=item C + +is a package name + +=item C + +is any of the above or an unblessed reference + +=back + +When used as an instance or class method (C<< $obj->isa( TYPE ) >>), +C returns I if $obj is blessed into package C or +inherits from package C. + +When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes +referred to as a static method), C returns I if C +inherits from (or is itself) the name of the package C or +inherits from package C. When used as a function, like @@ -71,7 +93,11 @@ unblessed reference to a perl variable of type C, such as "HASH", "ARRAY", or "Regexp". -=item $obj->can( METHOD ), CLASS->can( METHOD ), can( VAL, METHOD ) +=item C<< $obj->can( METHOD ) >> + +=item C<< CLASS->can( METHOD ) >> + +=item C C checks if the object or class has a method called C. If it does then a reference to the sub is returned. If it does not then I is @@ -95,15 +121,15 @@ If C is not a blessed reference, or if it does not have a method C, I is returned. -=item VERSION ( [ REQUIRE ] ) +=item C C will return the value of the variable C<$VERSION> in the package the object is blessed into. If C is given then it will do a comparison and die if the package version is not greater than or equal to C. -C can be called as either a class (static) method, an object method or -or a function. +C can be called as either a class (static) method, an object +method or or a function. =back ```
p5pRT commented 21 years ago

From Robin.Barker@npl.co.uk

There are also some collision of C\<> and -> in the UNIVERSAL.pm pod. The attached patch cleans up this and some other bits of the pod. My patch should be applied as well as (not instead of) Casey's.

Robin

--- ../perl@​19401/lib/UNIVERSAL.pm Thu Jan 23 14​:22​:55 2003 +++ lib/UNIVERSAL.pm @​@​ -41\,20 +41\,42 @​@​

=over 4

-=item $obj->isa( TYPE )\, CLASS->isa( TYPE )\, isa( VAL\, TYPE ) +=item C\<\< $obj->isa( TYPE ) >>

- C\ is a package name - $obj is a blessed reference or a string containing a package name - C\ is a package name - C\ is any of the above or an unblessed reference - -When used as an instance or class method (C\<$obj->isa( TYPE )>)\, C\ -returns I\ if $obj is blessed into package C\ or inherits from -package C\. - -When used as a class method (C\<CLASS->isa( TYPE )>; sometimes referred to as a -static method)\, C\ returns I\ if C\ inherits from (or is itself) -the name of the package C\ or inherits from package C\. +=item C\<\< CLASS->isa( TYPE ) >> + +=item C\<isa( VAL\, TYPE )> + +Where + +=over 4 + +=item C\ + +is a package name + +=item C\<$obj> + +is a blessed reference or a string containing a package name + +=item C\ + +is a package name + +=item C\ + +is any of the above or an unblessed reference + +=back + +When used as an instance or class method (C\<\< $obj->isa( TYPE ) >>)\, +C\ returns I\ if $obj is blessed into package C\ or +inherits from package C\. + +When used as a class method (C\<\< CLASS->isa( TYPE ) >>​: sometimes +referred to as a static method)\, C\ returns I\ if C\ +inherits from (or is itself) the name of the package C\ or +inherits from package C\.

When used as a function\, like

@​@​ -71\,7 +93\,11 @​@​ unblessed reference to a perl variable of type C\\, such as "HASH"\, "ARRAY"\, or "Regexp".

-=item $obj->can( METHOD )\, CLASS->can( METHOD )\, can( VAL\, METHOD ) +=item C\<\< $obj->can( METHOD ) >> + +=item C\<\< CLASS->can( METHOD ) >> + +=item C\<can( VAL\, METHOD )>

C\ checks if the object or class has a method called C\. If it does then a reference to the sub is returned. If it does not then I\ is @​@​ -95\,15 +121\,15 @​@​ If C\ is not a blessed reference\, or if it does not have a method C\\, I\ is returned.

-=item VERSION ( [ REQUIRE ] ) +=item C\<VERSION ( [ REQUIRE ] )>

C\ will return the value of the variable C\<$VERSION> in the package the object is blessed into. If C\ is given then it will do a comparison and die if the package version is not greater than or equal to C\.

-C\ can be called as either a class (static) method\, an object method or -or a function. +C\ can be called as either a class (static) method\, an object +method or or a function.

=back End of Patch

-----Original Message----- From​: Casey West [mailto​:casey@​geeknest.com] Sent​: 23 April 2003 15​:04 To​: perl5-porters@​perl.org Subject​: Re​: [perl #22018] UNIVERSAL documentation contradicts itself

It was Tuesday\, April 22\, 2003 when Marc Lehmann took the soap box\, saying​: : ----------------------------------------------------------------- : [Please enter your report here] : : SYNOPSIS says​: : : use UNIVERSAL qw( isa can VERSION ); : : DESCRIPTION says​: : : These subroutines should not be imported via "use UNIVERSAL : qw(...)". If you want simple local access to them you can do : : If an import shouldn't be used then it should be said why\, and if : imports can be used this paragraph should be dropped (I guess it wasn't : implemented but now is).

Your guess is correct. This patch cleans up the documentation to explain the import rules.

  Casey West

-- "I loathe people who keep dogs. They are cowards who haven't got the guts to bite people themselves." --August Strindberg

Inline Patch ```diff --- perl-current.orig/lib/UNIVERSAL.pm Mon Apr 21 10:50:06 2003 +++ perl-current/lib/UNIVERSAL.pm Wed Apr 23 09:53:32 2003 @@ -108,11 +108,10 @@ =back -These subroutines should I be imported via S

qw(...)>>. -If you want simple local access to them you can do +=head1 EXPORTS

- *isa = \&UNIVERSAL​::isa; +None by default.

-to import isa into your package. +You may request the import of all three functions C\\, C\\, and C\.

=cut

This e-mail and any attachments may contain confidential and/or privileged material; it is for the intended addressee(s) only. If you are not a named addressee\, you must not use\, retain or disclose such information.

NPL Management Ltd cannot guarantee that the e-mail or any attachments are free from viruses.

NPL Management Ltd. Registered in England and Wales. No​: 2937881 Registered Office​: Teddington\, Middlesex\, United Kingdom TW11 0LW.

p5pRT commented 21 years ago

From Robin.Barker@npl.co.uk

universal.pat

p5pRT commented 21 years ago

From Robin.Barker@npl.co.uk

This could go on for some time!

I am stuck behind an exchange server and I haven't learned how to do the right things with line wrapping in patches\, especially if those patches are to reduce paragraphs to \< 80 characters wide! I sent the patch as an attachment in the hope that would be OK.

In reviewing your version of my patch\, I saw a further typo. A repeated "or" was hidden over a line break - my reformatting made it obvious but I missed it.

Another patch\, to be applied after the others​:

--- lib/UNIVERSAL.pm.orig +++ lib/UNIVERSAL.pm @​@​ -129\,7 +129\,7 @​@​ greater than or equal to C\.

C\ can be called as either a class (static) method\, an object -method or or a function. +method or a function.

=back End of patch

Robin

-----Original Message----- From​: Casey West [mailto​:casey@​geeknest.com] Sent​: 23 April 2003 15​:36 To​: Robin Barker Cc​: perl5-porters@​perl.org; 'casey@​geeknest.com' Subject​: Re​: [PATCH lib/UNIVERSAL.pm] RE​: [perl #22018] UNIVERSAL documentatio n contradicts itself

It was Wednesday\, April 23\, 2003 when Robin Barker took the soap box\, saying​: : There are also some collision of C\<> and -> in the UNIVERSAL.pm pod. : The attached patch cleans up this and some other bits of the pod. : My patch should be applied as well as (not instead of) Casey's.

As well\, I forgot to address the question of 'if those functions should not be imported\, the documentation should say why'. So to your patch and my previous I add the patch below my signature.

Also\, your patch was a bit hard to apply because it seems that your mailer played wrapping games on it. I've attached a cleaned up copy of your patch.

  Casey West

-- I am a superhero.

Inline Patch ```diff --- perl-current.orig/lib/UNIVERSAL.pm Wed Apr 23 10:24:44 2003 +++ perl-current/lib/UNIVERSAL.pm Wed Apr 23 10:25:51 2003 @@ -138,6 +138,8 @@ None by default. -You may request the import of all three functions C, C, and ```

C. +You may request the import of all three functions (C\\, C\\, and +C\)\, however it isn't necessary to do so. Perl magically makes these +functions act as methods on all objects.

=cut

This e-mail and any attachments may contain confidential and/or privileged material; it is for the intended addressee(s) only. If you are not a named addressee\, you must not use\, retain or disclose such information.

NPL Management Ltd cannot guarantee that the e-mail or any attachments are free from viruses.

NPL Management Ltd. Registered in England and Wales. No​: 2937881 Registered Office​: Teddington\, Middlesex\, United Kingdom TW11 0LW.

p5pRT commented 21 years ago

From goldbb2@earthlink.net

Casey West wrote​: [snip]

-You may request the import of all three functions C\\, C\\, and C\. +You may request the import of all three functions (C\\, C\\, and +C\)\, however it isn't necessary to do so. Perl magically makes these +functions act as methods on all objects.

However\, one often needs/wants to use 'isa' as a function\, not as a method... especially if there's a chance that the item being examined isn't blessed. Thus\, one might want to import it.

-- $a=24;split//\,240513;s/\B/ => /for@​@​=qw(ac ab bc ba cb ca );{push(@​b\,$a)\,($a-=6)^=1 for 2..$a/6x--$|;print "$@​[$a%6 ]\n";((6\<=($a-=6))?$a+=$_[$a%6]-$a%6​:($a=pop @​b))&&redo;}

p5pRT commented 21 years ago

From @cwest

It was Wednesday\, April 23\, 2003 when Benjamin Goldberg took the soap box\, saying​: : Casey West wrote​: : [snip] : > -You may request the import of all three functions C\\, C\\, and C\. : > +You may request the import of all three functions (C\\, C\\, and : > +C\)\, however it isn't necessary to do so. Perl magically makes these : > +functions act as methods on all objects. : : However\, one often needs/wants to use 'isa' as a function\, not as a : method... especially if there's a chance that the item being examined : isn't blessed. Thus\, one might want to import it.

Indeed! Since the patching on top of patching on top of patching has grown rather gruesome I've taken a liberty to compile a complete patch consisting of all the previous ones.

  Casey West

-- Hit any user to continue.

Inline Patch ```diff --- perl-current.orig/lib/UNIVERSAL.pm Tue Nov 13 12:28:19 2001 +++ perl-current/lib/UNIVERSAL.pm Thu Apr 24 08:13:06 2003 @@ -41,20 +41,42 @@ =over 4 -=item $obj->isa( TYPE ), CLASS->isa( TYPE ), isa( VAL, TYPE ) +=item C<< $obj->isa( TYPE ) >> - C is a package name - $obj is a blessed reference or a string containing a package name - C is a package name - C is any of the above or an unblessed reference - -When used as an instance or class method (C<$obj->isa( TYPE )>), C -returns I if $obj is blessed into package C or inherits from -package C. - -When used as a class method (Cisa( TYPE )>; sometimes referred to as a -static method), C returns I if C inherits from (or is itself) -the name of the package C or inherits from package C. +=item C<< CLASS->isa( TYPE ) >> + +=item C + +Where + +=over 4 + +=item C + +is a package name + +=item C<$obj> + +is a blessed reference or a string containing a package name + +=item C + +is a package name + +=item C + +is any of the above or an unblessed reference + +=back + +When used as an instance or class method (C<< $obj->isa( TYPE ) >>), +C returns I if $obj is blessed into package C or +inherits from package C. + +When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes +referred to as a static method), C returns I if C +inherits from (or is itself) the name of the package C or +inherits from package C. When used as a function, like @@ -67,11 +89,15 @@ require UNIVERSAL ; $yes = UNIVERSAL::isa $a, "ARRAY"; -, C returns I in the same cases as above and also if C is an +C returns I in the same cases as above and also if C is an unblessed reference to a perl variable of type C, such as "HASH", "ARRAY", or "Regexp". -=item $obj->can( METHOD ), CLASS->can( METHOD ), can( VAL, METHOD ) +=item C<< $obj->can( METHOD ) >> + +=item C<< CLASS->can( METHOD ) >> + +=item C C checks if the object or class has a method called C. If it does then a reference to the sub is returned. If it does not then I is @@ -95,24 +121,27 @@ If C is not a blessed reference, or if it does not have a method C, I is returned. -=item VERSION ( [ REQUIRE ] ) +=item C C will return the value of the variable C<$VERSION> in the package the object is blessed into. If C is given then it will do a comparison and die if the package version is not greater than or equal to C. -C can be called as either a class (static) method, an object method or -or a function. +C can be called as either a class (static) method, an object +method or a function. =back -These subroutines should I be imported via S>. -If you want simple local access to them you can do +=head1 EXPORTS - *isa = \&UNIVERSAL::isa; +None by default. -to import isa into your package. +You may request the import of all three functions (C, C, and +C), however it isn't usually necessary to do so. Perl magically +makes these functions act as methods on all objects. The one exception is +C, which is useful as a function when operating on non-blessed +references. =cut ```
p5pRT commented 21 years ago

From @jhi

Indeed! Since the patching on top of patching on top of patching has grown rather gruesome I've taken a liberty to compile a complete patch consisting of all the previous ones.

Thanks\, applied (change #19348).

-- Jarkko Hietaniemi \jhi@&#8203;iki\.fi http​://www.iki.fi/jhi/ "There is this special biologist word we use for 'stable'. It is 'dead'." -- Jack Cohen

p5pRT commented 21 years ago

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