From: Brandon L Black Date: Mon, 4 Jun 2007 05:43:47 +0000 (+0000) Subject: 0.03, C3 reqs and loading mro.pm X-Git-Tag: 0.03^0 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cbb1ce9aa2f3960c349cb2eaac97608db8da07dd;p=gitmo%2FMRO-Compat.git 0.03, C3 reqs and loading mro.pm --- diff --git a/ChangeLog b/ChangeLog index efad0a1..a693fbe 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ Revision history for Perl extension MRO::Compat. +0.03 - Mon Jun 4, 2007 + - Bumped C3 requirements + - Loads mro.pm on 5.9.5+ + 0.02 - Sat May 12, 2007 - Added mro::get_pkg_gen (which optionally works even faster with Class::C3::XS 0.04) in diff --git a/Makefile.PL b/Makefile.PL index 5878ada..fb3b030 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -1,14 +1,21 @@ -use inc::Module::Install; +use inc::Module::Install 0.65; name 'MRO-Compat'; all_from 'lib/MRO/Compat.pm'; -build_requires 'Test::More' => '0.47'; +test_requires 'Test::More' => '0.47'; if($] < 5.009_005) { - feature 'XS Speedups', 'Class::C3::XS' => '0.04'; - requires 'Class::C3' => '0.18'; + feature 'XS Speedups', + 'Class::C3::XS' => '0.07'; + requires 'Class::C3' => '0.19'; } +# Rebuild README for maintainers +if(-e 'MANIFEST.SKIP') { + system("pod2text lib/MRO/Compat.pm >README"); +} + +auto_provides; auto_install; WriteAll; diff --git a/README b/README index 9e257d7..cecb019 100644 --- a/README +++ b/README @@ -1,25 +1,147 @@ -MRO::Compat version 0.02 -=========================== +NAME + MRO::Compat - mro::* interface compatibility for Perls < 5.9.5 -INSTALLATION +SYNOPSIS + package FooClass; use base qw/X Y Z/; + package X; use base qw/ZZZ/; + package Y; use base qw/ZZZ/; + package Z; use base qw/ZZZ/; -To install this module type the following: + package main; + use MRO::Compat; + my $linear = mro::get_linear_isa('FooClass'); + print join(q{, }, @$linear); - perl Makefile.PL - make - make test - make install + # Prints: "FooClass, X, ZZZ, Y, Z" -DEPENDENCIES +DESCRIPTION + The "mro" namespace provides several utilities for dealing with method + resolution order and method caching in general in Perl 5.9.5 and higher. - Requires Test::More 0.47 to test - Requires Class::C3 0.18 for runtime - Recommends Class::C3::XS 0.04 for runtime + This module provides those interfaces for earlier versions of Perl (back + to 5.6.0 anyways). -COPYRIGHT AND LICENCE + It is a harmless no-op to use this module on 5.9.5+. If you're writing a + piece of software that would like to use the parts of 5.9.5+'s mro:: + interfaces that are supported here, and you want compatibility with + older Perls, this is the module for you. -Copyright (C) 2007 Brandon L Black + Some parts of this interface will work better with Class::C3::XS + installed, but it's not a requirement. -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. + This module never exports any functions. All calls must be fully + qualified with the "mro::" prefix. + + The interface documentation here serves only as a quick reference of + what the function basically does, and what differences between + MRO::Compat and 5.9.5+ one should look out for. The main docs in 5.9.5's + mro are the real interface docs, and contain a lot of other useful + information. + +VERSION 0.02 + This is the first release of this new module, and on top of that, the + Perl 5.9.5 it seeks to provide compatibility with isn't even out yet. + + If you're going to use/depend on this, please keep abreast of possible + interface changes in the next few versions. Once Perl 5.9.5 is out the + door the interfaces should stabilize on whatever 5.9.5 has to offer. In + the meantime, don't be surprised if MRO::Compat and 5.9.5's interfaces + aren't perfectly in sync at all times. + +Functions + mro::get_linear_isa($classname[, $type]) + 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 "c3" or "dfs" if specified as $type). + + The linearized MRO of a class is a single ordered list of all of the + classes that would be visited in the process of resolving a method on + the given class, starting with itself. It does not include any duplicate + entries. + + Note that "UNIVERSAL" (and any members of "UNIVERSAL"'s MRO) are not + part of the MRO of a class, even though all classes implicitly inherit + methods from "UNIVERSAL" and its parents. + + mro::import + This allows the "use mro 'dfs'" and "use mro 'c3'" syntaxes, providing + you "use MRO::Compat" first. Please see the "USING C3" section for + additional details. + + mro::set_mro($classname, $type) + Sets the mro of $classname to one of the types "dfs" or "c3". Please see + the "USING C3" section for additional details. + + mro::get_mro($classname) + Returns the MRO of the given class (either "c3" or "dfs"). + + It considers any Class::C3-using class to have C3 MRO even before + Class::C3::initialize() is called. + + mro::get_isarev($classname) + Returns an arrayref of classes who are subclasses of the given + classname. In other words, classes who we exist, however indirectly, in + the @ISA inheritancy hierarchy of. + + This is much slower on pre-5.9.5 Perls with MRO::Compat than it is on + 5.9.5+, as it has to search the entire package namespace. + + mro::is_universal($classname) + Returns a boolean status indicating whether or not the given classname + is either "UNIVERSAL" itself, or one of "UNIVERSAL"'s parents by @ISA + inheritance. + + Any class for which this function returns true is "universal" in the + sense that all classes potentially inherit methods from it. + + mro::invalidate_all_method_caches + Increments "PL_sub_generation", which invalidates method caching in all + packages. + + Please note that this is rarely necessary, unless you are dealing with a + situation which is known to confuse Perl's method caching. + + mro::method_changed_in($classname) + Invalidates the method cache of any classes dependent on the given + class. In MRO::Compat on pre-5.9.5 Perls, this is an alias for + "mro::invalidate_all_method_caches" above, as pre-5.9.5 Perls have no + other way to do this. It will still enforce the requirement that you + pass it a classname, for compatibility. + + Please note that this is rarely necessary, unless you are dealing with a + situation which is known to confuse Perl's method caching. + + mro::get_pkg_gen($classname) + Returns an integer which is incremented every time a local method of or + the @ISA of the given package changes on Perl 5.9.5+. On earlier Perls + with this MRO::Compat module, it will probably increment a lot more + often than necessary. + +USING C3 + While this module makes the 5.9.5+ syntaxes "use mro 'c3'" and + "mro::set_mro("Foo", 'c3')" available on older Perls, it does so merely + by passing off the work to Class::C3. + + It does not remove the need for you to call Class::C3's "initialize()", + "reinitialize()", and/or "uninitialize()" at the appropriate times as + documented in the Class::C3 docs. + + Because MRO::Compat has Class::C3 as a pre-requisite, and requires it at + "use" time, you can blindly call those functions in code that uses + MRO::Compat. Under 5.9.5+ with MRO::Compat, your calls to those + functions will become a no-op and everything will work fine. + +SEE ALSO + Class::C3 + + mro + +AUTHOR + Brandon L. Black, + +COPYRIGHT AND LICENSE + Copyright 2007 Brandon L. Black + + This library is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. diff --git a/lib/MRO/Compat.pm b/lib/MRO/Compat.pm index 0dfb5f9..d55f9a9 100644 --- a/lib/MRO/Compat.pm +++ b/lib/MRO/Compat.pm @@ -5,14 +5,15 @@ require 5.006_000; # Keep this < 1.00, so people can tell the fake # mro.pm from the real one -our $VERSION = '0.02'; +our $VERSION = '0.03'; BEGIN { # Alias our private functions over to # the mro:: namespace and load # Class::C3 if Perl < 5.9.5 if($] < 5.009_005) { - $mro::VERSION = $VERSION; + $mro::VERSION # to fool Module::Install when generating META.yml + = $VERSION; $INC{'mro.pm'} = 'Faked by MRO::Compat'; *mro::import = \&__import; *mro::get_linear_isa = \&__get_linear_isa;