1NAME
2 Class::ISA -- report the search path for a class's ISA tree
3
4SYNOPSIS
5 # Suppose you go: use Food::Fishstick, and that uses and
6 # inherits from other things, which in turn use and inherit
7 # from other things. And suppose, for sake of brevity of
8 # example, that their ISA tree is the same as:
9
10 @Food::Fishstick::ISA = qw(Food::Fish Life::Fungus Chemicals);
11 @Food::Fish::ISA = qw(Food);
12 @Food::ISA = qw(Matter);
13 @Life::Fungus::ISA = qw(Life);
14 @Chemicals::ISA = qw(Matter);
15 @Life::ISA = qw(Matter);
16 @Matter::ISA = qw();
17
18 use Class::ISA;
19 print "Food::Fishstick path is:\n ",
20 join(", ", Class::ISA::super_path('Food::Fishstick')),
21 "\n";
22
23 That prints:
24
25 Food::Fishstick path is:
26 Food::Fish, Food, Matter, Life::Fungus, Life, Chemicals
27
28DESCRIPTION
29 Suppose you have a class (like Food::Fish::Fishstick) that is derived,
30 via its @ISA, from one or more superclasses (as Food::Fish::Fishstick is
31 from Food::Fish, Life::Fungus, and Chemicals), and some of those
32 superclasses may themselves each be derived, via its @ISA, from one or
33 more superclasses (as above).
34
35 When, then, you call a method in that class ($fishstick->calories), Perl
36 first searches there for that method, but if it's not there, it goes
37 searching in its superclasses, and so on, in a depth-first (or maybe
38 "height-first" is the word) search. In the above example, it'd first
39 look in Food::Fish, then Food, then Matter, then Life::Fungus, then
40 Life, then Chemicals.
41
42 This library, Class::ISA, provides functions that return that list --
43 the list (in order) of names of classes Perl would search to find a
44 method, with no duplicates.
45
46FUNCTIONS
47 the function Class::ISA::super_path($CLASS)
48 This returns the ordered list of names of classes that Perl would
49 search thru in order to find a method, with no duplicates in the
50 list. $CLASS is not included in the list. UNIVERSAL is not included
51 -- if you need to consider it, add it to the end.
52
53 the function Class::ISA::self_and_super_path($CLASS)
54 Just like "super_path", except that $CLASS is included as the first
55 element.
56
57 the function Class::ISA::self_and_super_versions($CLASS)
58 This returns a hash whose keys are $CLASS and its
59 (super-)superclasses, and whose values are the contents of each
60 class's $VERSION (or undef, for classes with no $VERSION).
61
62 The code for self_and_super_versions is meant to serve as an example
63 for precisely the kind of tasks I anticipate that
64 self_and_super_path and super_path will be used for. You are
65 strongly advised to read the source for self_and_super_versions, and
66 the comments there.
67
68CAUTIONARY NOTES
69 * Class::ISA doesn't export anything. You have to address the functions
70 with a "Class::ISA::" on the front.
71
72 * Contrary to its name, Class::ISA isn't a class; it's just a package.
73 Strange, isn't it?
74
75 * Say you have a loop in the ISA tree of the class you're calling one of
76 the Class::ISA functions on: say that Food inherits from Matter, but
77 Matter inherits from Food (for sake of argument). If Perl, while
78 searching for a method, actually discovers this cyclicity, it will throw
79 a fatal error. The functions in Class::ISA effectively ignore this
80 cyclicity; the Class::ISA algorithm is "never go down the same path
81 twice", and cyclicities are just a special case of that.
82
83 * The Class::ISA functions just look at @ISAs. But theoretically, I
84 suppose, AUTOLOADs could bypass Perl's ISA-based search mechanism and do
85 whatever they please. That would be bad behavior, tho; and I try not to
86 think about that.
87
88 * If Perl can't find a method anywhere in the ISA tree, it then looks in
89 the magical class UNIVERSAL. This is rarely relevant to the tasks that I
90 expect Class::ISA functions to be put to, but if it matters to you, then
91 instead of this:
92
93 @supers = Class::Tree::super_path($class);
94
95 do this:
96
97 @supers = (Class::Tree::super_path($class), 'UNIVERSAL');
98
99 And don't say no-one ever told ya!
100
101 * When you call them, the Class::ISA functions look at @ISAs anew --
102 that is, there is no memoization, and so if ISAs change during runtime,
103 you get the current ISA tree's path, not anything memoized. However,
104 changing ISAs at runtime is probably a sign that you're out of your
105 mind!
106
107COPYRIGHT AND LICENSE
108 Copyright (c) 1999-2009 Sean M. Burke. All rights reserved.
109
110 This library is free software; you can redistribute it and/or modify it
111 under the same terms as Perl itself.
112
113AUTHOR
114 Sean M. Burke "sburke@cpan.org"
115
116MAINTAINER
117 Maintained by Steffen Mueller "smueller@cpan.org".
118
119