diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/UNIVERSAL.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/UNIVERSAL.3pm | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/UNIVERSAL.3pm b/upstream/mageia-cauldron/man3pm/UNIVERSAL.3pm new file mode 100644 index 00000000..c965e1ee --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/UNIVERSAL.3pm @@ -0,0 +1,258 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "UNIVERSAL 3pm" +.TH UNIVERSAL 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +UNIVERSAL \- base class for ALL classes (blessed references) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& my $obj_is_io = $fd\->isa("IO::Handle"); +\& my $cls_is_io = Class\->isa("IO::Handle"); +\& +\& my $obj_does_log = $obj\->DOES("Logger"); +\& my $cls_does_log = Class\->DOES("Logger"); +\& +\& my $obj_sub = $obj\->can("print"); +\& my $cls_sub = Class\->can("print"); +\& +\& my $eval_sub = eval { $ref\->can("fandango") }; +\& my $ver = $obj\->VERSION; +\& +\& # but never do this! +\& my $is_io = UNIVERSAL::isa($fd, "IO::Handle"); +\& my $sub = UNIVERSAL::can($obj, "print"); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`UNIVERSAL\*(C'\fR is the base class from which all blessed references inherit. +See perlobj. +.PP +\&\f(CW\*(C`UNIVERSAL\*(C'\fR provides the following methods: +.ie n .IP """$obj\->isa( TYPE )""" 4 +.el .IP "\f(CW$obj\->isa( TYPE )\fR" 4 +.IX Item "$obj->isa( TYPE )" +.PD 0 +.ie n .IP """CLASS\->isa( TYPE )""" 4 +.el .IP "\f(CWCLASS\->isa( TYPE )\fR" 4 +.IX Item "CLASS->isa( TYPE )" +.ie n .IP """eval { VAL\->isa( TYPE ) }""" 4 +.el .IP "\f(CWeval { VAL\->isa( TYPE ) }\fR" 4 +.IX Item "eval { VAL->isa( TYPE ) }" +.PD +Where +.RS 4 +.ie n .IP """TYPE""" 4 +.el .IP \f(CWTYPE\fR 4 +.IX Item "TYPE" +is a package name +.ie n .IP $obj 4 +.el .IP \f(CW$obj\fR 4 +.IX Item "$obj" +is a blessed reference or a package name +.ie n .IP """CLASS""" 4 +.el .IP \f(CWCLASS\fR 4 +.IX Item "CLASS" +is a package name +.ie n .IP """VAL""" 4 +.el .IP \f(CWVAL\fR 4 +.IX Item "VAL" +is any of the above or an unblessed reference +.RE +.RS 4 +.Sp +When used as an instance or class method (\f(CW\*(C`$obj\->isa( TYPE )\*(C'\fR), +\&\f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW$obj\fR is blessed into package \f(CW\*(C`TYPE\*(C'\fR or +inherits from package \f(CW\*(C`TYPE\*(C'\fR. +.Sp +When used as a class method (\f(CW\*(C`CLASS\->isa( TYPE )\*(C'\fR, sometimes +referred to as a static method), \f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW\*(C`CLASS\*(C'\fR +inherits from (or is itself) the name of the package \f(CW\*(C`TYPE\*(C'\fR or +inherits from package \f(CW\*(C`TYPE\*(C'\fR. +.Sp +If you're not sure what you have (the \f(CW\*(C`VAL\*(C'\fR case), wrap the method call in an +\&\f(CW\*(C`eval\*(C'\fR block to catch the exception if \f(CW\*(C`VAL\*(C'\fR is undefined or an unblessed +reference. The \f(CW\*(C`isa\*(C'\fR operator is an +alternative that simply returns false in this case, so the \f(CW\*(C`eval\*(C'\fR is not +needed. +.Sp +If you want to be sure that you're calling \f(CW\*(C`isa\*(C'\fR as a method, not a class, +check the invocand with \f(CW\*(C`blessed\*(C'\fR from Scalar::Util first: +.Sp +.Vb 1 +\& use Scalar::Util \*(Aqblessed\*(Aq; +\& +\& if ( blessed( $obj ) && $obj\->isa("Some::Class") ) { +\& ... +\& } +.Ve +.RE +.ie n .IP """$obj\->DOES( ROLE )""" 4 +.el .IP "\f(CW$obj\->DOES( ROLE )\fR" 4 +.IX Item "$obj->DOES( ROLE )" +.PD 0 +.ie n .IP """CLASS\->DOES( ROLE )""" 4 +.el .IP "\f(CWCLASS\->DOES( ROLE )\fR" 4 +.IX Item "CLASS->DOES( ROLE )" +.PD +\&\f(CW\*(C`DOES\*(C'\fR checks if the object or class performs the role \f(CW\*(C`ROLE\*(C'\fR. A role is a +named group of specific behavior (often methods of particular names and +signatures), similar to a class, but not necessarily a complete class by +itself. For example, logging or serialization may be roles. +.Sp +\&\f(CW\*(C`DOES\*(C'\fR and \f(CW\*(C`isa\*(C'\fR are similar, in that if either is true, you know that the +object or class on which you call the method can perform specific behavior. +However, \f(CW\*(C`DOES\*(C'\fR is different from \f(CW\*(C`isa\*(C'\fR in that it does not care \fIhow\fR the +invocand performs the operations, merely that it does. (\f(CW\*(C`isa\*(C'\fR of course +mandates an inheritance relationship. Other relationships include aggregation, +delegation, and mocking.) +.Sp +By default, classes in Perl only perform the \f(CW\*(C`UNIVERSAL\*(C'\fR role, as well as the +role of all classes in their inheritance. In other words, by default \f(CW\*(C`DOES\*(C'\fR +responds identically to \f(CW\*(C`isa\*(C'\fR. +.Sp +There is a relationship between roles and classes, as each class implies the +existence of a role of the same name. There is also a relationship between +inheritance and roles, in that a subclass that inherits from an ancestor class +implicitly performs any roles its parent performs. Thus you can use \f(CW\*(C`DOES\*(C'\fR in +place of \f(CW\*(C`isa\*(C'\fR safely, as it will return true in all places where \f(CW\*(C`isa\*(C'\fR will +return true (provided that any overridden \f(CW\*(C`DOES\*(C'\fR \fIand\fR \f(CW\*(C`isa\*(C'\fR methods behave +appropriately). +.ie n .IP """$obj\->can( METHOD )""" 4 +.el .IP "\f(CW$obj\->can( METHOD )\fR" 4 +.IX Item "$obj->can( METHOD )" +.PD 0 +.ie n .IP """CLASS\->can( METHOD )""" 4 +.el .IP "\f(CWCLASS\->can( METHOD )\fR" 4 +.IX Item "CLASS->can( METHOD )" +.ie n .IP """eval { VAL\->can( METHOD ) }""" 4 +.el .IP "\f(CWeval { VAL\->can( METHOD ) }\fR" 4 +.IX Item "eval { VAL->can( METHOD ) }" +.PD +\&\f(CW\*(C`can\*(C'\fR checks if the object or class has a method called \f(CW\*(C`METHOD\*(C'\fR. If it does, +then it returns a reference to the sub. If it does not, then it returns +\&\fIundef\fR. This includes methods inherited or imported by \f(CW$obj\fR, \f(CW\*(C`CLASS\*(C'\fR, or +\&\f(CW\*(C`VAL\*(C'\fR. +.Sp +\&\f(CW\*(C`can\*(C'\fR cannot know whether an object will be able to provide a method through +AUTOLOAD (unless the object's class has overridden \f(CW\*(C`can\*(C'\fR appropriately), so a +return value of \fIundef\fR does not necessarily mean the object will not be able +to handle the method call. To get around this some module authors use a forward +declaration (see perlsub) for methods they will handle via AUTOLOAD. For +such 'dummy' subs, \f(CW\*(C`can\*(C'\fR will still return a code reference, which, when +called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided, +calling the coderef will cause an error. +.Sp +You may call \f(CW\*(C`can\*(C'\fR as a class (static) method or an object method. +.Sp +Again, the same rule about having a valid invocand applies \-\- use an \f(CW\*(C`eval\*(C'\fR +block or \f(CW\*(C`blessed\*(C'\fR if you need to be extra paranoid. +.ie n .IP """VERSION ( [ REQUIRE ] )""" 4 +.el .IP "\f(CWVERSION ( [ REQUIRE ] )\fR" 4 +.IX Item "VERSION ( [ REQUIRE ] )" +\&\f(CW\*(C`VERSION\*(C'\fR will return the value of the variable \f(CW$VERSION\fR in the +package the object is blessed into. If \f(CW\*(C`REQUIRE\*(C'\fR is given then +it will do a comparison and die if the package version is not +greater than or equal to \f(CW\*(C`REQUIRE\*(C'\fR, or if either \f(CW$VERSION\fR or \f(CW\*(C`REQUIRE\*(C'\fR +is not a "lax" version number (as defined by the version module). +.Sp +The return from \f(CW\*(C`VERSION\*(C'\fR will actually be the stringified version object +using the package \f(CW$VERSION\fR scalar, which is guaranteed to be equivalent +but may not be precisely the contents of the \f(CW$VERSION\fR scalar. If you want +the actual contents of \f(CW$VERSION\fR, use \f(CW$CLASS::VERSION\fR instead. +.Sp +\&\f(CW\*(C`VERSION\*(C'\fR can be called as either a class (static) method or an object +method. +.SH WARNINGS +.IX Header "WARNINGS" +\&\fBNOTE:\fR \f(CW\*(C`can\*(C'\fR directly uses Perl's internal code for method lookup, and +\&\f(CW\*(C`isa\*(C'\fR uses a very similar method and cache-ing strategy. This may cause +strange effects if the Perl code dynamically changes \f(CW@ISA\fR in any package. +.PP +You may add other methods to the UNIVERSAL class via Perl or XS code. +You do not need to \f(CW\*(C`use UNIVERSAL\*(C'\fR to make these methods +available to your program (and you should not do so). +.SH EXPORTS +.IX Header "EXPORTS" +None. +.PP +Previous versions of this documentation suggested using \f(CW\*(C`isa\*(C'\fR as +a function to determine the type of a reference: +.PP +.Vb 2 +\& $yes = UNIVERSAL::isa($h, "HASH"); +\& $yes = UNIVERSAL::isa("Foo", "Bar"); +.Ve +.PP +The problem is that this code would \fInever\fR call an overridden \f(CW\*(C`isa\*(C'\fR method in +any class. Instead, use \f(CW\*(C`reftype\*(C'\fR from Scalar::Util for the first case: +.PP +.Vb 1 +\& use Scalar::Util \*(Aqreftype\*(Aq; +\& +\& $yes = reftype( $h ) eq "HASH"; +.Ve +.PP +and the method form of \f(CW\*(C`isa\*(C'\fR for the second: +.PP +.Vb 1 +\& $yes = Foo\->isa("Bar"); +.Ve |