Class::ISA(3pm)

okay so bestie, welcome to Class::ISA(3pm) 💖 this is a real page from the User Contributed Perl Documentation and it's lowkey iconic, so let's get into it 🎀

---

🌸 NAME 🌸

Class::ISA — report the search path for a class's ISA tree ✨

---

🦋 SYNOPSIS 🦋

# Suppose you go: use Food::Fishstick, and that uses and
# inherits from other things, which in turn use and inherit
# from other things.  And suppose, for sake of brevity of
# example, that their ISA tree is the same as:

@Food::Fishstick::ISA = qw(Food::Fish  Life::Fungus  Chemicals);
@Food::Fish::ISA = qw(Food);
@Food::ISA = qw(Matter);
@Life::Fungus::ISA = qw(Life);
@Chemicals::ISA = qw(Matter);
@Life::ISA = qw(Matter);
@Matter::ISA = qw();

use Class::ISA;
print "Food::Fishstick path is:\n ",
      join(", ", Class::ISA::super_path('Food::Fishstick')),
      "\n";

and bestie, that prints this:

Food::Fishstick path is:
 Food::Fish, Food, Matter, Life::Fungus, Life, Chemicals

---

💅 DESCRIPTION 💅

so picture this 🌈 you've got a class — say Food::Fish::Fishstick — that's derived, through its @ISA, from one or more superclasses (like how Food::Fish::Fishstick comes from Food::Fish, Life::Fungus, and Chemicals). and some of those superclasses might themselves each be derived, through their @ISA, from one or more superclasses (literally exactly like the example above). it's giving family tree 🫶

so then when you call a method in that class ($fishstick->calories), Perl first searches there for that method, and if it's not there? it goes searching in its superclasses, and then in their superclasses, and so on forever — it's a depth-first search (or maybe "height-first" is the word, iykyk). in the example above, Perl would first look in Food::Fish, then Food, then Matter, then Life::Fungus, then Life, then Chemicals. that's the whole order, no skips 👑

this library, Class::ISA, hands you functions that return that exact list — the list, in order, of the names of the classes Perl would search to find a method, with no duplicates ✨

---

🔥 FUNCTIONS 🔥

✨ the function Class::ISA::super_path($CLASS)

this returns the ordered list of names of classes that Perl would search thru in order to find a method, with no duplicates in the list. note bestie: $CLASS is not included in the list. and UNIVERSAL is not included either — if you need to consider it, you gotta add it to the end yourself 💀

✨ the function Class::ISA::self_and_super_path($CLASS)

literally just like super_path, except that $CLASS is included, as the very first element. main character energy, it goes first 🎀

✨ the function Class::ISA::self_and_super_versions($CLASS)

this returns a hash whose keys are $CLASS and its (super-)superclasses, and whose values are the contents of each class's $VERSION (or undef, for classes with no $VERSION). slay 💜

the code for self_and_super_versions is meant to serve as an example for precisely the kind of tasks the author anticipates that self_and_super_path and super_path will be used for. you are strongly advised to read the source for self_and_super_versions, and the comments there 📖

---

🙈 CAUTIONARY NOTES 🙈

• Class::ISA doesn't export anything. you have to address the functions with a Class::ISA:: on the front. no shortcuts bestie 😭
• contrary to its name, Class::ISA isn't a class; it's just a package. strange, isn't it? 💀
• say you have a loop in the ISA tree of the class you're calling one of the Class::ISA functions on: say that Food inherits from Matter, but Matter inherits from Food (for sake of argument). if Perl, while searching for a method, actually discovers this cyclicity, it will throw a fatal error. the functions in Class::ISA effectively ignore this cyclicity; the Class::ISA algorithm is "never go down the same path twice", and cyclicities are just a special case of that 🌀
• the Class::ISA functions just look at @ISAs. but theoretically, I suppose, AUTOLOADs could bypass Perl's ISA-based search mechanism and do whatever they please. that would be bad behavior, tho; and the author tries not to think about that 🙈
• if Perl can't find a method anywhere in the ISA tree, it then looks in the magical class UNIVERSAL. this is rarely relevant to the tasks that the author expects Class::ISA functions to be put to, but if it matters to you, then instead of this:

@supers = Class::Tree::super_path($class);

do this:

@supers = (Class::Tree::super_path($class), 'UNIVERSAL');

and don't say no-one ever told ya! 💅

• when you call them, the Class::ISA functions look at @ISAs anew — that is, there is no memoization, and so if ISAs change during runtime, you get the current ISA tree's path, not anything memoized. however, changing ISAs at runtime is probably a sign that you're out of your mind! 😭

---

👑 COPYRIGHT AND LICENSE 👑

Copyright (c) 1999-2009 Sean M. Burke. All rights reserved.

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself ✨

---

🎀 AUTHOR 🎀

Sean M. Burke "sburke@cpan.org"

---

💜 MAINTAINER 💜

maintained by Steffen Mueller "smueller@cpan.org".

---

and that's the whole thing bestie, no cap 🫶 this page ships with perl v5.36.0 and is dated 2022-11-21 — so go forth and trace your ISA trees, you gorgeous nerd 🌸🦋⭐