README

   1 NAME
   2     MRO::Compat - mro::* interface compatibility for Perls < 5.9.5
   3
   4 SYNOPSIS
   5        package FooClass; use base qw/X Y Z/;
   6        package X;        use base qw/ZZZ/;
   7        package Y;        use base qw/ZZZ/;
   8        package Z;        use base qw/ZZZ/;
   9
  10        package main;
  11        use MRO::Compat;
  12        my $linear = mro::get_linear_isa('FooClass');
  13        print join(q{, }, @$linear);
  14
  15        # Prints: "FooClass, X, ZZZ, Y, Z"
  16
  17 DESCRIPTION
  18     The "mro" namespace provides several utilities for dealing with method
  19     resolution order and method caching in general in Perl 5.9.5 and higher.
  20
  21     This module provides those interfaces for earlier versions of Perl (back
  22     to 5.6.0 anyways).
  23
  24     It is a harmless no-op to use this module on 5.9.5+. That is to say,
  25     code which properly uses MRO::Compat will work unmodified on both older
  26     Perls and 5.9.5+.
  27
  28     If you're writing a piece of software that would like to use the parts
  29     of 5.9.5+'s mro:: interfaces that are supported here, and you want
  30     compatibility with older Perls, this is the module for you.
  31
  32     Some parts of this code will work better and/or faster with
  33     Class::C3::XS installed (which is an optional prereq of Class::C3, which
  34     is in turn a prereq of this package), but it's not a requirement.
  35
  36     This module never exports any functions. All calls must be fully
  37     qualified with the "mro::" prefix.
  38
  39     The interface documentation here serves only as a quick reference of
  40     what the function basically does, and what differences between
  41     MRO::Compat and 5.9.5+ one should look out for. The main docs in 5.9.5's
  42     mro are the real interface docs, and contain a lot of other useful
  43     information.
  44
  45 Functions
  46   mro::get_linear_isa($classname[, $type])
  47     Returns an arrayref which is the linearized MRO of the given class. Uses
  48     whichever MRO is currently in effect for that class by default, or the
  49     given MRO (either "c3" or "dfs" if specified as $type).
  50
  51     The linearized MRO of a class is a single ordered list of all of the
  52     classes that would be visited in the process of resolving a method on
  53     the given class, starting with itself. It does not include any duplicate
  54     entries.
  55
  56     Note that "UNIVERSAL" (and any members of "UNIVERSAL"'s MRO) are not
  57     part of the MRO of a class, even though all classes implicitly inherit
  58     methods from "UNIVERSAL" and its parents.
  59
  60   mro::import
  61     This allows the "use mro 'dfs'" and "use mro 'c3'" syntaxes, providing
  62     you "use MRO::Compat" first. Please see the "USING C3" section for
  63     additional details.
  64
  65   mro::set_mro($classname, $type)
  66     Sets the mro of $classname to one of the types "dfs" or "c3". Please see
  67     the "USING C3" section for additional details.
  68
  69   mro::get_mro($classname)
  70     Returns the MRO of the given class (either "c3" or "dfs").
  71
  72     It considers any Class::C3-using class to have C3 MRO even before
  73     Class::C3::initialize() is called.
  74
  75   mro::get_isarev($classname)
  76     Returns an arrayref of classes who are subclasses of the given
  77     classname. In other words, classes who we exist, however indirectly, in
  78     the @ISA inheritancy hierarchy of.
  79
  80     This is much slower on pre-5.9.5 Perls with MRO::Compat than it is on
  81     5.9.5+, as it has to search the entire package namespace.
  82
  83   mro::is_universal($classname)
  84     Returns a boolean status indicating whether or not the given classname
  85     is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA
  86     inheritance.
  87
  88     Any class for which this function returns true is "universal" in the
  89     sense that all classes potentially inherit methods from it.
  90
  91   mro::invalidate_all_method_caches
  92     Increments "PL_sub_generation", which invalidates method caching in all
  93     packages.
  94
  95     Please note that this is rarely necessary, unless you are dealing with a
  96     situation which is known to confuse Perl's method caching.
  97
  98   mro::method_changed_in($classname)
  99     Invalidates the method cache of any classes dependent on the given
 100     class. In MRO::Compat on pre-5.9.5 Perls, this is an alias for
 101     "mro::invalidate_all_method_caches" above, as pre-5.9.5 Perls have no
 102     other way to do this. It will still enforce the requirement that you
 103     pass it a classname, for compatibility.
 104
 105     Please note that this is rarely necessary, unless you are dealing with a
 106     situation which is known to confuse Perl's method caching.
 107
 108   mro::get_pkg_gen($classname)
 109     Returns an integer which is incremented every time a local method of or
 110     the @ISA of the given package changes on Perl 5.9.5+. On earlier Perls
 111     with this MRO::Compat module, it will probably increment a lot more
 112     often than necessary.
 113
 114 USING C3
 115     While this module makes the 5.9.5+ syntaxes "use mro 'c3'" and
 116     "mro::set_mro("Foo", 'c3')" available on older Perls, it does so merely
 117     by passing off the work to Class::C3.
 118
 119     It does not remove the need for you to call "Class::C3::initialize()",
 120     "Class::C3::reinitialize()", and/or "Class::C3::uninitialize()" at the
 121     appropriate times as documented in the Class::C3 docs. These three
 122     functions are always provided by MRO::Compat, either via Class::C3
 123     itself on older Perls, or directly as no-ops on 5.9.5+.
 124
 125 SEE ALSO
 126     Class::C3
 127
 128     mro
 129
 130 AUTHOR
 131     Brandon L. Black, <blblack@gmail.com>
 132
 133 COPYRIGHT AND LICENSE
 134     Copyright 2007 Brandon L. Black <blblack@gmail.com>
 135
 136     This library is free software; you can redistribute it and/or modify it
 137     under the same terms as Perl itself.
 138