local-lib5/man/man3/MRO::Compat.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "MRO::Compat 3"
 132 .TH MRO::Compat 3 "2009-05-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 MRO::Compat \- mro::* interface compatibility for Perls < 5.9.5
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&   package FooClass; use base qw/X Y Z/;
 139 \&   package X;        use base qw/ZZZ/;
 140 \&   package Y;        use base qw/ZZZ/;
 141 \&   package Z;        use base qw/ZZZ/;
 142 .Ve
 143 .PP
 144 .Vb 4
 145 \&   package main;
 146 \&   use MRO::Compat;
 147 \&   my $linear = mro::get_linear_isa('FooClass');
 148 \&   print join(q{, }, @$linear);
 149 .Ve
 150 .PP
 151 .Vb 1
 152 \&   # Prints: "FooClass, X, ZZZ, Y, Z"
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 The \*(L"mro\*(R" namespace provides several utilities for dealing
 157 with method resolution order and method caching in general
 158 in Perl 5.9.5 and higher.
 159 .PP
 160 This module provides those interfaces for
 161 earlier versions of Perl (back to 5.6.0 anyways).
 162 .PP
 163 It is a harmless no-op to use this module on 5.9.5+.  That
 164 is to say, code which properly uses MRO::Compat will work
 165 unmodified on both older Perls and 5.9.5+.
 166 .PP
 167 If you're writing a piece of software that would like to use
 168 the parts of 5.9.5+'s mro:: interfaces that are supported
 169 here, and you want compatibility with older Perls, this
 170 is the module for you.
 171 .PP
 172 Some parts of this code will work better and/or faster with
 173 Class::C3::XS installed (which is an optional prereq
 174 of Class::C3, which is in turn a prereq of this
 175 package), but it's not a requirement.
 176 .PP
 177 This module never exports any functions.  All calls must
 178 be fully qualified with the \f(CW\*(C`mro::\*(C'\fR prefix.
 179 .PP
 180 The interface documentation here serves only as a quick
 181 reference of what the function basically does, and what
 182 differences between MRO::Compat and 5.9.5+ one should
 183 look out for.  The main docs in 5.9.5's mro are the real
 184 interface docs, and contain a lot of other useful information.
 185 .SH "Functions"
 186 .IX Header "Functions"
 187 .ie n .Sh "mro::get_linear_isa($classname[, $type])"
 188 .el .Sh "mro::get_linear_isa($classname[, \f(CW$type\fP])"
 189 .IX Subsection "mro::get_linear_isa($classname[, $type])"
 190 Returns an arrayref which is the linearized \*(L"\s-1ISA\s0\*(R" of the given class.
 191 Uses whichever \s-1MRO\s0 is currently in effect for that class by default,
 192 or the given \s-1MRO\s0 (either \f(CW\*(C`c3\*(C'\fR or \f(CW\*(C`dfs\*(C'\fR if specified as \f(CW$type\fR).
 193 .PP
 194 The linearized \s-1ISA\s0 of a class is a single ordered list of all of the
 195 classes that would be visited in the process of resolving a method
 196 on the given class, starting with itself.  It does not include any
 197 duplicate entries.
 198 .PP
 199 Note that \f(CW\*(C`UNIVERSAL\*(C'\fR (and any members of \f(CW\*(C`UNIVERSAL\*(C'\fR's \s-1MRO\s0) are not
 200 part of the \s-1MRO\s0 of a class, even though all classes implicitly inherit
 201 methods from \f(CW\*(C`UNIVERSAL\*(C'\fR and its parents.
 202 .Sh "mro::import"
 203 .IX Subsection "mro::import"
 204 This allows the \f(CW\*(C`use mro 'dfs'\*(C'\fR and
 205 \&\f(CW\*(C`use mro 'c3'\*(C'\fR syntaxes, providing you
 206 \&\*(L"use MRO::Compat\*(R" first.  Please see the
 207 \&\*(L"\s-1USING\s0 C3\*(R" section for additional details.
 208 .ie n .Sh "mro::set_mro($classname, $type)"
 209 .el .Sh "mro::set_mro($classname, \f(CW$type\fP)"
 210 .IX Subsection "mro::set_mro($classname, $type)"
 211 Sets the mro of \f(CW$classname\fR to one of the types
 212 \&\f(CW\*(C`dfs\*(C'\fR or \f(CW\*(C`c3\*(C'\fR.  Please see the \*(L"\s-1USING\s0 C3\*(R"
 213 section for additional details.
 214 .Sh "mro::get_mro($classname)"
 215 .IX Subsection "mro::get_mro($classname)"
 216 Returns the \s-1MRO\s0 of the given class (either \f(CW\*(C`c3\*(C'\fR or \f(CW\*(C`dfs\*(C'\fR).
 217 .PP
 218 It considers any Class::C3\-using class to have C3 \s-1MRO\s0
 219 even before \fIClass::C3::initialize()\fR is called.
 220 .Sh "mro::get_isarev($classname)"
 221 .IX Subsection "mro::get_isarev($classname)"
 222 Returns an arrayref of classes who are subclasses of the
 223 given classname.  In other words, classes in whose \f(CW@ISA\fR
 224 hierarchy we appear, no matter how indirectly.
 225 .PP
 226 This is much slower on pre\-5.9.5 Perls with MRO::Compat
 227 than it is on 5.9.5+, as it has to search the entire
 228 package namespace.
 229 .Sh "mro::is_universal($classname)"
 230 .IX Subsection "mro::is_universal($classname)"
 231 Returns a boolean status indicating whether or not
 232 the given classname is either \f(CW\*(C`UNIVERSAL\*(C'\fR itself,
 233 or one of \f(CW\*(C`UNIVERSAL\*(C'\fR's parents by \f(CW@ISA\fR inheritance.
 234 .PP
 235 Any class for which this function returns true is
 236 \&\*(L"universal\*(R" in the sense that all classes potentially
 237 inherit methods from it.
 238 .Sh "mro::invalidate_all_method_caches"
 239 .IX Subsection "mro::invalidate_all_method_caches"
 240 Increments \f(CW\*(C`PL_sub_generation\*(C'\fR, which invalidates method
 241 caching in all packages.
 242 .PP
 243 Please note that this is rarely necessary, unless you are
 244 dealing with a situation which is known to confuse Perl's
 245 method caching.
 246 .Sh "mro::method_changed_in($classname)"
 247 .IX Subsection "mro::method_changed_in($classname)"
 248 Invalidates the method cache of any classes dependent on the
 249 given class.  In MRO::Compat on pre\-5.9.5 Perls, this is
 250 an alias for \f(CW\*(C`mro::invalidate_all_method_caches\*(C'\fR above, as
 251 pre\-5.9.5 Perls have no other way to do this.  It will still
 252 enforce the requirement that you pass it a classname, for
 253 compatibility.
 254 .PP
 255 Please note that this is rarely necessary, unless you are
 256 dealing with a situation which is known to confuse Perl's
 257 method caching.
 258 .Sh "mro::get_pkg_gen($classname)"
 259 .IX Subsection "mro::get_pkg_gen($classname)"
 260 Returns an integer which is incremented every time a local
 261 method of or the \f(CW@ISA\fR of the given package changes on
 262 Perl 5.9.5+.  On earlier Perls with this MRO::Compat module,
 263 it will probably increment a lot more often than necessary.
 264 .SH "USING C3"
 265 .IX Header "USING C3"
 266 While this module makes the 5.9.5+ syntaxes
 267 \&\f(CW\*(C`use mro 'c3'\*(C'\fR and \f(CW\*(C`mro::set_mro("Foo", 'c3')\*(C'\fR available
 268 on older Perls, it does so merely by passing off the work
 269 to Class::C3.
 270 .PP
 271 It does not remove the need for you to call
 272 \&\f(CW\*(C`Class::C3::initialize()\*(C'\fR, \f(CW\*(C`Class::C3::reinitialize()\*(C'\fR, and/or
 273 \&\f(CW\*(C`Class::C3::uninitialize()\*(C'\fR at the appropriate times
 274 as documented in the Class::C3 docs.  These three functions
 275 are always provided by MRO::Compat, either via Class::C3
 276 itself on older Perls, or directly as no-ops on 5.9.5+.
 277 .SH "SEE ALSO"
 278 .IX Header "SEE ALSO"
 279 Class::C3
 280 .PP
 281 mro
 282 .SH "AUTHOR"
 283 .IX Header "AUTHOR"
 284 Brandon L. Black, <blblack@gmail.com>
 285 .SH "COPYRIGHT AND LICENSE"
 286 .IX Header "COPYRIGHT AND LICENSE"
 287 Copyright 2007\-2008 Brandon L. Black <blblack@gmail.com>
 288 .PP
 289 This library is free software; you can redistribute it and/or modify
 290 it under the same terms as Perl itself.