=head1 SYNOPSIS
- use mro 'dfs'; # enable DFS mro for this class (Perl default)
- use mro 'c3'; # enable C3 mro for this class
+ use mro 'dfs'; # enable DFS MRO for this class (Perl default)
+ use mro 'c3'; # enable C3 MRO for this class
=head1 DESCRIPTION
=head1 OVERVIEW
-One can change the mro of a given class by either C<use mro>
-as shown in the synopsis, or by using the L</mro::set_mro>
-function below. The functions below do not require that one
-loads the "mro" module, they are provided by the core. The
-C<use mro> syntax is just syntax sugar for setting the current
-package's mro.
+It's possible to change the MRO of a given class either by using C<use
+mro> as shown in the synopsis, or by using the L</mro::set_mro> function
+below. The functions do not require loading the C<mro> module, as they
+are actually provided by the core perl interpreter. The C<use mro> syntax
+is just syntactic sugar for setting the current package's MRO.
=head1 The C3 MRO
In addition to the traditional Perl default MRO (depth first
-search, called C<dfs> here), Perl now offers the C3 MRO as
+search, called C<DFS> here), Perl now offers the C3 MRO as
well. Perl's support for C3 is based on the work done in
-Stevan Little's L<Class::C3>, and most of the C3-related
+Stevan Little's module L<Class::C3>, and most of the C3-related
documentation here is ripped directly from there.
=head2 What is C3?
-C3 is the name of an algorithm which aims to provide a sane method resolution order under multiple
-inheritence. It was first introduced in the langauge Dylan (see links in the L<SEE ALSO> section),
-and then later adopted as the prefered MRO (Method Resolution Order) for the new-style classes in
-Python 2.3. Most recently it has been adopted as the 'canonical' MRO for Perl 6 classes, and the
-default MRO for Parrot objects as well.
+C3 is the name of an algorithm which aims to provide a sane method
+resolution order under multiple inheritance. It was first introduced in
+the language Dylan (see links in the L</"SEE ALSO"> section), and then
+later adopted as the preferred MRO (Method Resolution Order) for the
+new-style classes in Python 2.3. Most recently it has been adopted as the
+"canonical" MRO for Perl 6 classes, and the default MRO for Parrot objects
+as well.
-=head2 How does C3 work.
+=head2 How does C3 work
-C3 works by always preserving local precendence ordering. This essentially means that no class will appear before any of it's subclasses. Take the classic diamond inheritence pattern for instance:
+C3 works by always preserving local precendence ordering. This essentially
+means that no class will appear before any of its subclasses. Take, for
+instance, the classic diamond inheritance pattern:
<A>
/ \
\ /
<D>
-The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A> appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO algorithm however, produces the following MRO (D, B, C, A), which does not have this same issue.
+The standard Perl 5 MRO would be (D, B, A, C). The result being that B<A>
+appears before B<C>, even though B<C> is the subclass of B<A>. The C3 MRO
+algorithm however, produces the following order: (D, B, C, A), which does
+not have this issue.
-This example is fairly trival, for more complex examples and a deeper explaination, see the links in the L<SEE ALSO - C3 Links> section.
+This example is fairly trivial; for more complex cases and a deeper
+explanation, see the links in the L</"SEE ALSO"> section.
=head1 Functions
-=head2 mro::get_linear_isa
+=head2 mro::get_linear_isa($classname[, $type])
-Arguments: classname[, type]
-
-Return an arrayref which is the linearized MRO of the given class.
+Returns an arrayref which is the linearized MRO of the given class.
Uses whichever MRO is currently in effect for that class by default,
-or the given mro (either C<c3> or C<dfs> if specified as C<type>).
+or the given MRO (either C<c3> or C<dfs> if specified as C<$type>).
-C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not part
-of the MRO of a class, even though all classes implicitly inherit
+Note that C<UNIVERSAL> (and any members of C<UNIVERSAL>'s MRO) are not
+part of the MRO of a class, even though all classes implicitly inherit
methods from C<UNIVERSAL> and its parents.
-=head2 mro::set_mro
-
-Arguments: classname, type
+=head2 mro::set_mro($classname, $type)
-Sets the MRO of the given class to the C<type> argument (either
+Sets the MRO of the given class to the C<$type> argument (either
C<c3> or C<dfs>).
-=head2 mro::get_mro
-
-Arguments: classname
+=head2 mro::get_mro($classname)
-Returns the MRO of the given class (either C<c3> or C<dfs>)
+Returns the MRO of the given class (either C<c3> or C<dfs>).
-=head2 mro::get_isarev
-
-Arguments: classname
+=head2 mro::get_isarev($classname)
Gets the C<mro_isarev> for this class, returned as an
-array of classnames. These are every class that "isa"
-the given classname, even if the isa relationship is
-indirect. This is used internally by the mro code to
-keep track of method/mro cache invalidations.
+array of class names. These are every class that "isa"
+the given class name, even if the isa relationship is
+indirect. This is used internally by the MRO code to
+keep track of method/MRO cache invalidations.
Currently, this list only grows, it never shrinks. This
was a performance consideration (properly tracking and
every class in existence, even though all classes are
effectively descendants for method inheritance purposes.
-=head2 mro::is_universal
-
-Arguments: classname
+=head2 mro::is_universal($classname)
Returns a boolean status indicating whether or not
the given classname is either C<UNIVERSAL> itself,
permanent. Once it is set, it does not go away, even
if the class in question really isn't universal anymore.
-=head2 mro::get_global_sub_generation
+=head2 mro::get_global_sub_generation()
-Arguments: none
+Returns the current value of the internal perl variable
+C<PL_sub_generation>.
-Returns the current value of C<PL_sub_generation>.
-
-=head2 mro::invalidate_all_method_caches
-
-Arguments: none
+=head2 mro::invalidate_all_method_caches()
Increments C<PL_sub_generation>, which invalidates method
caching in all packages.
-=head2 mro::get_sub_generation
-
-Arguments: classname
+=head2 mro::get_sub_generation($classname)
Returns the current value of a given package's C<sub_generation>.
This is only incremented when necessary for that package.
-If one is trying to determine whether significant (method/cache-
-affecting) changes have occured for a given stash since you last
-checked, you should check both this and the global one above.
-
-=head2 mro::method_changed_in
+If one is trying to determine whether significant (method/cache-affecting)
+changes have occured for a given stash since you last checked, you should
+check both this and the global one above.
-Arguments: classname
+=head2 mro::method_changed_in($classname)
-Invalidates the method cache of any classes dependant on the
+Invalidates the method cache of any classes dependent on the
given class.
=head2 next::method
sub some_method {
my $self = shift;
-
my $superclass_answer = $self->next::method(@_);
return $superclass_answer + 1;
}
The way it resolves which actual method to call is:
-1) First, it determines the linearized C3 MRO of
+=over 4
+
+=item 1
+
+First, it determines the linearized C3 MRO of
the object or class it is being called on.
-2) Then, it determines the class and method name
+=item 2
+
+Then, it determines the class and method name
of the context it was invoked from.
-3) Finally, it searches down the C3 MRO list until
+=item 3
+
+Finally, it searches down the C3 MRO list until
it reaches the contextually enclosing class, then
searches further down the MRO list for the next
method with the same name as the contextually
enclosing method.
+=back
+
Failure to find a next method will result in an
exception being thrown (see below for alternatives).
This is substantially different than the behavior
-of C<SUPER> under complex multiple inheritance,
-(this becomes obvious when one realizes that the
+of C<SUPER> under complex multiple inheritance.
+(This becomes obvious when one realizes that the
common superclasses in the C3 linearizations of
a given class and one of its parents will not
-always be ordered the same for both).
+always be ordered the same for both.)
-Caveat - Calling C<next::method> from methods defined outside the class:
+B<Caveat>: Calling C<next::method> from methods defined outside the class:
-There is an edge case when using C<next::method> from within a subroutine which was created in a different module than the one it is called from. It sounds complicated, but it really isn't. Here is an example which will not work correctly:
+There is an edge case when using C<next::method> from within a subroutine
+which was created in a different module than the one it is called from. It
+sounds complicated, but it really isn't. Here is an example which will not
+work correctly:
*Foo::foo = sub { (shift)->next::method(@_) };
-The problem exists because the anonymous subroutine being assigned to the glob C<*Foo::foo> will show up in the call stack as being called C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses C<caller> to find the name of the method it was called in, it will fail in this case.
+The problem exists because the anonymous subroutine being assigned to the
+C<*Foo::foo> glob will show up in the call stack as being called
+C<__ANON__> and not C<foo> as you might expect. Since C<next::method> uses
+C<caller> to find the name of the method it was called in, it will fail in
+this case.
+
+But fear not, there's a simple solution. The module C<Sub::Name> will
+reach into the perl internals and assign a name to an anonymous subroutine
+for you. Simply do this:
-But fear not, there is a simple solution. The module C<Sub::Name> will reach into the perl internals and assign a name to an anonymous subroutine for you. Simply do this:
-
use Sub::Name 'subname';
*Foo::foo = subname 'Foo::foo' => sub { (shift)->next::method(@_) };
=head2 next::can
-Like C<next::method>, but just returns either
-a code reference or C<undef> to indicate that
-no further methods of this name exist.
+This is similar to C<next::method>, but just returns either a code
+reference or C<undef> to indicate that no further methods of this name
+exist.
=head2 maybe::next::method
-In simple cases it is equivalent to:
+In simple cases, it is equivalent to:
$self->next::method(@_) if $self->next_can;
But there are some cases where only this solution
-works (like "goto &maybe::next::method");
+works (like C<goto &maybe::next::method>);
-=head1 SEE ALSO - C3 Links
+=head1 SEE ALSO
=head2 The original Dylan paper
projects / p5sagit/p5-mst-13.2.git / commitdiff