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 | |
cbb1ce9a |
24 | It is a harmless no-op to use this module on 5.9.5+. If you're writing a |
25 | piece of software that would like to use the parts of 5.9.5+'s mro:: |
26 | interfaces that are supported here, and you want compatibility with |
27 | older Perls, this is the module for you. |
4c4e4170 |
28 | |
cbb1ce9a |
29 | Some parts of this interface will work better with Class::C3::XS |
30 | installed, but it's not a requirement. |
4c4e4170 |
31 | |
cbb1ce9a |
32 | This module never exports any functions. All calls must be fully |
33 | qualified with the "mro::" prefix. |
34 | |
35 | The interface documentation here serves only as a quick reference of |
36 | what the function basically does, and what differences between |
37 | MRO::Compat and 5.9.5+ one should look out for. The main docs in 5.9.5's |
38 | mro are the real interface docs, and contain a lot of other useful |
39 | information. |
40 | |
41 | VERSION 0.02 |
42 | This is the first release of this new module, and on top of that, the |
43 | Perl 5.9.5 it seeks to provide compatibility with isn't even out yet. |
44 | |
45 | If you're going to use/depend on this, please keep abreast of possible |
46 | interface changes in the next few versions. Once Perl 5.9.5 is out the |
47 | door the interfaces should stabilize on whatever 5.9.5 has to offer. In |
48 | the meantime, don't be surprised if MRO::Compat and 5.9.5's interfaces |
49 | aren't perfectly in sync at all times. |
50 | |
51 | Functions |
52 | mro::get_linear_isa($classname[, $type]) |
53 | Returns an arrayref which is the linearized MRO of the given class. Uses |
54 | whichever MRO is currently in effect for that class by default, or the |
55 | given MRO (either "c3" or "dfs" if specified as $type). |
56 | |
57 | The linearized MRO of a class is a single ordered list of all of the |
58 | classes that would be visited in the process of resolving a method on |
59 | the given class, starting with itself. It does not include any duplicate |
60 | entries. |
61 | |
62 | Note that "UNIVERSAL" (and any members of "UNIVERSAL"'s MRO) are not |
63 | part of the MRO of a class, even though all classes implicitly inherit |
64 | methods from "UNIVERSAL" and its parents. |
65 | |
66 | mro::import |
67 | This allows the "use mro 'dfs'" and "use mro 'c3'" syntaxes, providing |
68 | you "use MRO::Compat" first. Please see the "USING C3" section for |
69 | additional details. |
70 | |
71 | mro::set_mro($classname, $type) |
72 | Sets the mro of $classname to one of the types "dfs" or "c3". Please see |
73 | the "USING C3" section for additional details. |
74 | |
75 | mro::get_mro($classname) |
76 | Returns the MRO of the given class (either "c3" or "dfs"). |
77 | |
78 | It considers any Class::C3-using class to have C3 MRO even before |
79 | Class::C3::initialize() is called. |
80 | |
81 | mro::get_isarev($classname) |
82 | Returns an arrayref of classes who are subclasses of the given |
83 | classname. In other words, classes who we exist, however indirectly, in |
84 | the @ISA inheritancy hierarchy of. |
85 | |
86 | This is much slower on pre-5.9.5 Perls with MRO::Compat than it is on |
87 | 5.9.5+, as it has to search the entire package namespace. |
88 | |
89 | mro::is_universal($classname) |
90 | Returns a boolean status indicating whether or not the given classname |
91 | is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA |
92 | inheritance. |
93 | |
94 | Any class for which this function returns true is "universal" in the |
95 | sense that all classes potentially inherit methods from it. |
96 | |
97 | mro::invalidate_all_method_caches |
98 | Increments "PL_sub_generation", which invalidates method caching in all |
99 | packages. |
100 | |
101 | Please note that this is rarely necessary, unless you are dealing with a |
102 | situation which is known to confuse Perl's method caching. |
103 | |
104 | mro::method_changed_in($classname) |
105 | Invalidates the method cache of any classes dependent on the given |
106 | class. In MRO::Compat on pre-5.9.5 Perls, this is an alias for |
107 | "mro::invalidate_all_method_caches" above, as pre-5.9.5 Perls have no |
108 | other way to do this. It will still enforce the requirement that you |
109 | pass it a classname, for compatibility. |
110 | |
111 | Please note that this is rarely necessary, unless you are dealing with a |
112 | situation which is known to confuse Perl's method caching. |
113 | |
114 | mro::get_pkg_gen($classname) |
115 | Returns an integer which is incremented every time a local method of or |
116 | the @ISA of the given package changes on Perl 5.9.5+. On earlier Perls |
117 | with this MRO::Compat module, it will probably increment a lot more |
118 | often than necessary. |
119 | |
120 | USING C3 |
121 | While this module makes the 5.9.5+ syntaxes "use mro 'c3'" and |
122 | "mro::set_mro("Foo", 'c3')" available on older Perls, it does so merely |
123 | by passing off the work to Class::C3. |
124 | |
125 | It does not remove the need for you to call Class::C3's "initialize()", |
126 | "reinitialize()", and/or "uninitialize()" at the appropriate times as |
127 | documented in the Class::C3 docs. |
128 | |
129 | Because MRO::Compat has Class::C3 as a pre-requisite, and requires it at |
130 | "use" time, you can blindly call those functions in code that uses |
131 | MRO::Compat. Under 5.9.5+ with MRO::Compat, your calls to those |
132 | functions will become a no-op and everything will work fine. |
133 | |
134 | SEE ALSO |
135 | Class::C3 |
136 | |
137 | mro |
138 | |
139 | AUTHOR |
140 | Brandon L. Black, <blblack@gmail.com> |
141 | |
142 | COPYRIGHT AND LICENSE |
143 | Copyright 2007 Brandon L. Black <blblack@gmail.com> |
144 | |
145 | This library is free software; you can redistribute it and/or modify it |
146 | under the same terms as Perl itself. |
4c4e4170 |
147 | |