mingw/html/lib/Class/ISA.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Class::ISA -- report the search path for a class's ISA tree</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Class::ISA -- report the search path for a class's ISA tree</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#functions">FUNCTIONS</a></li>
  26         <li><a href="#cautionary_notes">CAUTIONARY NOTES</a></li>
  27         <li><a href="#copyright">COPYRIGHT</a></li>
  28         <li><a href="#author">AUTHOR</a></li>
  29 </ul>
  30 <!-- INDEX END -->
  31
  32 <hr />
  33 <p>
  34 </p>
  35 <h1><a name="name">NAME</a></h1>
  36 <p>Class::ISA -- report the search path for a class's ISA tree</p>
  37 <p>
  38 </p>
  39 <hr />
  40 <h1><a name="synopsis">SYNOPSIS</a></h1>
  41 <pre>
  42   # Suppose you go: use Food::Fishstick, and that uses and
  43   # inherits from other things, which in turn use and inherit
  44   # from other things.  And suppose, for sake of brevity of
  45   # example, that their ISA tree is the same as:</pre>
  46 <pre>
  47   @Food::Fishstick::ISA = qw(Food::Fish  Life::Fungus  Chemicals);
  48   @Food::Fish::ISA = qw(Food);
  49   @Food::ISA = qw(Matter);
  50   @Life::Fungus::ISA = qw(Life);
  51   @Chemicals::ISA = qw(Matter);
  52   @Life::ISA = qw(Matter);
  53   @Matter::ISA = qw();</pre>
  54 <pre>
  55   use Class::ISA;
  56   print &quot;Food::Fishstick path is:\n &quot;,
  57         join(&quot;, &quot;, Class::ISA::super_path('Food::Fishstick')),
  58         &quot;\n&quot;;</pre>
  59 <p>That prints:</p>
  60 <pre>
  61   Food::Fishstick path is:
  62    Food::Fish, Food, Matter, Life::Fungus, Life, Chemicals</pre>
  63 <p>
  64 </p>
  65 <hr />
  66 <h1><a name="description">DESCRIPTION</a></h1>
  67 <p>Suppose you have a class (like Food::Fish::Fishstick) that is derived,
  68 via its @ISA, from one or more superclasses (as Food::Fish::Fishstick
  69 is from Food::Fish, Life::Fungus, and Chemicals), and some of those
  70 superclasses may themselves each be derived, via its @ISA, from one or
  71 more superclasses (as above).</p>
  72 <p>When, then, you call a method in that class ($fishstick-&gt;calories),
  73 Perl first searches there for that method, but if it's not there, it
  74 goes searching in its superclasses, and so on, in a depth-first (or
  75 maybe ``height-first'' is the word) search.  In the above example, it'd
  76 first look in Food::Fish, then Food, then Matter, then Life::Fungus,
  77 then Life, then Chemicals.</p>
  78 <p>This library, Class::ISA, provides functions that return that list --
  79 the list (in order) of names of classes Perl would search to find a
  80 method, with no duplicates.</p>
  81 <p>
  82 </p>
  83 <hr />
  84 <h1><a name="functions">FUNCTIONS</a></h1>
  85 <dl>
  86 <dt><strong><a name="item_super_path">the function Class::ISA::super_path($CLASS)</a></strong>
  87
  88 <dd>
  89 <p>This returns the ordered list of names of classes that Perl would
  90 search thru in order to find a method, with no duplicates in the list.
  91 $CLASS is not included in the list.  UNIVERSAL is not included -- if
  92 you need to consider it, add it to the end.</p>
  93 </dd>
  94 </li>
  95 <dt><strong><a name="item_self_and_super_path">the function Class::ISA::self_and_super_path($CLASS)</a></strong>
  96
  97 <dd>
  98 <p>Just like <a href="#item_super_path"><code>super_path</code></a>, except that $CLASS is included as the first
  99 element.</p>
 100 </dd>
 101 </li>
 102 <dt><strong><a name="item_self_and_super_versions">the function Class::ISA::self_and_super_versions($CLASS)</a></strong>
 103
 104 <dd>
 105 <p>This returns a hash whose keys are $CLASS and its
 106 (super-)superclasses, and whose values are the contents of each
 107 class's $VERSION (or undef, for classes with no $VERSION).</p>
 108 </dd>
 109 <dd>
 110 <p>The code for self_and_super_versions is meant to serve as an example
 111 for precisely the kind of tasks I anticipate that self_and_super_path
 112 and super_path will be used for.  You are strongly advised to read the
 113 source for self_and_super_versions, and the comments there.</p>
 114 </dd>
 115 </li>
 116 </dl>
 117 <p>
 118 </p>
 119 <hr />
 120 <h1><a name="cautionary_notes">CAUTIONARY NOTES</a></h1>
 121 <p>* Class::ISA doesn't export anything.  You have to address the
 122 functions with a ``Class::ISA::'' on the front.</p>
 123 <p>* Contrary to its name, Class::ISA isn't a class; it's just a package.
 124 Strange, isn't it?</p>
 125 <p>* Say you have a loop in the ISA tree of the class you're calling one
 126 of the Class::ISA functions on: say that Food inherits from Matter,
 127 but Matter inherits from Food (for sake of argument).  If Perl, while
 128 searching for a method, actually discovers this cyclicity, it will
 129 throw a fatal error.  The functions in Class::ISA effectively ignore
 130 this cyclicity; the Class::ISA algorithm is ``never go down the same
 131 path twice'', and cyclicities are just a special case of that.</p>
 132 <p>* The Class::ISA functions just look at @ISAs.  But theoretically, I
 133 suppose, AUTOLOADs could bypass Perl's ISA-based search mechanism and
 134 do whatever they please.  That would be bad behavior, tho; and I try
 135 not to think about that.</p>
 136 <p>* If Perl can't find a method anywhere in the ISA tree, it then looks
 137 in the magical class UNIVERSAL.  This is rarely relevant to the tasks
 138 that I expect Class::ISA functions to be put to, but if it matters to
 139 you, then instead of this:</p>
 140 <pre>
 141   @supers = Class::Tree::super_path($class);</pre>
 142 <p>do this:</p>
 143 <pre>
 144   @supers = (Class::Tree::super_path($class), 'UNIVERSAL');</pre>
 145 <p>And don't say no-one ever told ya!</p>
 146 <p>* When you call them, the Class::ISA functions look at @ISAs anew --
 147 that is, there is no memoization, and so if ISAs change during
 148 runtime, you get the current ISA tree's path, not anything memoized.
 149 However, changing ISAs at runtime is probably a sign that you're out
 150 of your mind!</p>
 151 <p>
 152 </p>
 153 <hr />
 154 <h1><a name="copyright">COPYRIGHT</a></h1>
 155 <p>Copyright (c) 1999, 2000 Sean M. Burke. All rights reserved.</p>
 156 <p>This library is free software; you can redistribute it and/or modify
 157 it under the same terms as Perl itself.</p>
 158 <p>
 159 </p>
 160 <hr />
 161 <h1><a name="author">AUTHOR</a></h1>
 162 <p>Sean M. Burke <code>sburke@cpan.org</code></p>
 163 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 164 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 165 <big><strong><span class="block">&nbsp;Class::ISA -- report the search path for a class's ISA tree</span></strong></big>
 166 </td></tr>
 167 </table>
 168
 169 </body>
 170
 171 </html>