Commit | Line | Data |
cbb1ce9a |
1 | NAME |
2 | MRO::Compat - mro::* interface compatibility for Perls < 5.9.5 |
4c4e4170 |
3 | |
cbb1ce9a |
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/; |
4c4e4170 |
9 | |
cbb1ce9a |
10 | package main; |
11 | use MRO::Compat; |
12 | my $linear = mro::get_linear_isa('FooClass'); |
13 | print join(q{, }, @$linear); |
4c4e4170 |
14 | |
cbb1ce9a |
15 | # Prints: "FooClass, X, ZZZ, Y, Z" |
4c4e4170 |
16 | |
cbb1ce9a |
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. |
4c4e4170 |
20 | |
cbb1ce9a |
21 | This module provides those interfaces for earlier versions of Perl (back |
22 | to 5.6.0 anyways). |
4c4e4170 |
23 | |
81350029 |
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+. |
4c4e4170 |
27 | |
81350029 |
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. |
4c4e4170 |
35 | |
cbb1ce9a |
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 | |
cbb1ce9a |
45 | Functions |
46 | mro::get_linear_isa($classname[, $type]) |
602f6319 |
47 | Returns an arrayref which is the linearized "ISA" of the given class. |
48 | Uses whichever MRO is currently in effect for that class by default, or |
49 | the given MRO (either "c3" or "dfs" if specified as $type). |
cbb1ce9a |
50 | |
602f6319 |
51 | The linearized ISA of a class is a single ordered list of all of the |
cbb1ce9a |
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 | |
81350029 |
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+. |
cbb1ce9a |
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 |
602f6319 |
134 | Copyright 2007-2008 Brandon L. Black <blblack@gmail.com> |
cbb1ce9a |
135 | |
136 | This library is free software; you can redistribute it and/or modify it |
137 | under the same terms as Perl itself. |
4c4e4170 |
138 | |