lib/mro.pm

   1 package mro;
   2 use strict;
   3 use warnings;
   4
   5 # mro.pm versions >= 1.00 reserved for the Perl core
   6 our $VERSION = '0.01';
   7
   8 our $C3_INSTALLED;
   9 BEGIN {
  10     eval { require Class::C3 };
  11     if(!$@) {
  12         $C3_INSTALLED = 1;
  13     }
  14 }
  15
  16 sub import {
  17     die q{The "use mro 'foo'" syntax is only supported on Perl 5.9.5+}
  18         if $_[1];
  19 }
  20
  21 =head1 NAME
  22
  23 mro - Method Resolution Order
  24
  25 =head1 SYNOPSIS
  26
  27    package FooClass; use base qw/X Y Z/;
  28    package X;        use base qw/ZZZ/;
  29    package Y;        use base qw/ZZZ/;
  30    package Z;        use base qw/ZZZ/;
  31
  32    package main;
  33    use mro;
  34    my $linear = mro::get_linear_isa('FooClass');
  35    print join(q{, }, @$linear) . "\n";
  36
  37    # Prints: "FooClass, X, ZZZ, Y, Z"
  38
  39 =head1 DESCRIPTION
  40
  41 The "mro" namespace provides several utilities for dealing
  42 with method resolution order and method caching in general.
  43
  44 It never exports any functions.  All calls must be fully
  45 qualified with the C<mro::> prefix.
  46
  47 =head1 IMPORTANT INFORMATION
  48
  49 This module is only for use on Perls earlier than 5.9.5.
  50 Perl version 5.9.5 and higher includes its own superior
  51 implementation, with a version number greater than 1.00.
  52
  53 This CPAN implementation supports a small subset of the
  54 features of the 5.9.5+ version, to make it easier for
  55 some classes of modules to depend on these features and
  56 be compatible with older Perls.
  57
  58 =head1 Functions
  59
  60 =head2 mro::get_linear_isa($classname[, $type])
  61
  62 Returns an arrayref which is the linearized MRO of the given class.
  63 Uses whichever MRO is currently in effect for that class by default,
  64 or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
  65
  66 The linearized MRO of a class is a single ordered list of all of the
  67 classes that would be visited in the process of resolving a method
  68 on the given class, starting with itself.  It does not include any
  69 duplicate entries.
  70
  71 Explicitly asking for the C<c3> MRO of a class will die if
  72 L<Class::C3> is not installed.  If L<Class::C3> is installed, it will
  73 detect C3 classes and return the correct C3 MRO unless explicitly
  74 asked to return the C<dfs> MRO.
  75
  76 Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
  77 part of the MRO of a class, even though all classes implicitly inherit
  78 methods from C<UNIVERSAL> and its parents.
  79
  80 =head2 mro::set_mro($classname, $type)
  81
  82 Not supported in this version, will die if used.
  83
  84 =head2 mro::get_mro($classname)
  85
  86 Returns the MRO of the given class (either C<c3> or C<dfs>).
  87
  88 =head2 mro::get_isarev($classname)
  89
  90 Not supported in this version, will die if used.
  91
  92 =head2 mro::is_universal($classname)
  93
  94 Returns a boolean status indicating whether or not
  95 the given classname is either C<UNIVERSAL> itself,
  96 or one of C<UNIVERSAL>'s parents by C<@ISA> inheritance.
  97
  98 Any class for which this function returns true is
  99 "universal" in the sense that all classes potentially
 100 inherit methods from it.
 101
 102 =head2 mro::invalidate_all_method_caches()
 103
 104 Increments C<PL_sub_generation>, which invalidates method
 105 caching in all packages.
 106
 107 =head2 mro::method_changed_in($classname)
 108
 109 Invalidates the method cache of any classes dependent on the
 110 given class.  In this version, this is an alias for
 111 C<mro::invalidate_all_method_caches> above, as pre-5.9.5
 112 Perls have no other way to do this.  It will still enforce
 113 the requirement that you pass it a classname, for
 114 compatibility with 5.9.5.
 115
 116 =head1 SEE ALSO
 117
 118 L<Class::C3>
 119
 120 =head1 AUTHOR
 121
 122 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
 123
 124 =head1 COPYRIGHT AND LICENSE
 125
 126 Copyright 2007 Brandon L. Black E<lt>blblack@gmail.comE<gt>
 127
 128 This library is free software; you can redistribute it and/or modify
 129 it under the same terms as Perl itself.
 130
 131 =cut
 132
 133 1;