Class::Handle(3pm)

💖 Class::Handle — a whole vibe 💖

okay bestie, so this is the page for Class::Handle, a Perl module (it's a 3pm manpage, yes, very official, very demure) by Adam Kennedy, and it's literally just a cute little object wrapper so you can do class stuff without losing your mind. let's get into it 🫶

---

✨ NAME ✨

Class::Handle — Create objects that are handles to Classes 💅

---

🌸 SYNOPSIS 🌸

# Create a class handle
use Class::Handle;
my $class = Class::Handle->new( 'Foo::Class' );
my $name = $class->name;

# UNIVERSAL type methods
$class->VERSION();
$class->isa( 'Foo:Bar' );
$class->can( 'blah' );

# Class::Inspector type methods
$class->installed();
$class->loaded();
$class->filename();
$class->resolved_filename();
$class->functions();
$class->function_refs();
$class->function_exists( 'function' );
$class->methods( 'public', 'full' );
$class->subclasses();

# Class::ISA type methods
$class->super_path();
$class->self_and_super_path();
$class->full_super_path();

# Loading and unloading
$class->load();

---

🦋 DESCRIPTION 🦋

so here's the tea: all the class-related functionality in Perl is scattered across like, a million different modules, and it's giving chaos. Class::Handle is here to fix that by being a convenient little object wrapper around all the different types of functions you can run on a class. iconic behaviour, honestly. 👑

⚠️ real talk though: this is an initial non-production quality release, and you should treat it exactly like that. Functionality and API are subject to change without notice. no cap. don't be surprised, bestie.

Currently, Class::Handle provides what is effectively a combined API from UNIVERSAL, Class::ISA and Class::Inspector for obtaining information about a Class, plus some additional task methods, like load, for common tasks relating to classes. it's the group project where everyone actually did their part. 🌈

---

👑 UNIVERSAL API 👑

so that we keep compliance with other classes that rely on methods provided by UNIVERSAL, Class::Handle acts in the normal way when something like <Class::Handle->VERSION> is called. that is, it returns the version of Class::Handle itself. yes, itself. main character energy, it's about her. ✨

BUT — when UNIVERSAL methods are called on an instantiation, the method is changed to act on the class we have a handle to. so the two following statements are equivalent, fr fr:

# Getting the version directly
print Foo::Bar->VERSION;

# Getting the version via Class::Handle
my $class = Class::Handle->new( 'Foo::Bar' );
print $class->VERSION;

this also applies to the isa and can methods. slay. 💅

---

🎀 METHODS 🎀

new $class

the new constructor will create a new handle to a class of unknown existence or status. that is, it won't check that the class actually exists at this time. it WILL however check to make sure that your class name is legal. it has standards. 🧚

• Returns a new Class::Handle object on success
• Returns undef if the class name is illegal

---

name

the name method returns the name of the class as originally specified in the constructor. it remembers where it came from. 🥹

---

VERSION

find the version for the class. does not check that the class is loaded ( at this time ).

Returns the version on success, undef if the class does not define a $VERSION or the class is not loaded.

---

isa $class

checks to see if the class is a subclass of another class. does not check that the class is loaded ( at this time ).

Returns true/false as for UNIVERSAL::isa.

---

can $method

checks to see if a particular method is defined for the class.

Returns a CODE ref to the function if the method is available, or false if the class does not have that method available.

---

installed

checks to see if a particular class is installed on the machine, or at least that the class is available to perl. in this case, class really means module. this method cannot detect a class that is not a module. ( Has its own file ). 📁

Returns true if the class is installed and available, or false otherwise.

---

loaded

checks to see if a class is loaded. in this case, class does NOT mean module. the loaded method will return true for classes that do not have their own file. sneaky little things. 🙈

for example, if a module Foo contains the classes Foo, Foo::Bar and Foo::Buffy, the loaded method will return true for all of the classes.

Returns true if the class is loaded, or false otherwise.

---

filename

Returns the base filename for a class. for example, for the class Foo::Bar, loaded would return Foo/Bar.pm.

the filename method is platform neutral — it should always return the filename in the correct format for your platform. 🌍 considerate queen.

---

resolved_filename @extra_paths

the resolved_filename will attempt to find the real file on your system that will be used when a class is loaded. if additional paths are provided as arguments, they will be tried first, before the contents of the @INC array. if a file cannot be found to match the class, returns false. 🔍

---

loaded_filename

if the class is loaded, returns the name of the file that it was originally loaded from.

Returns false if the class is not loaded, or did not have its own file.

---

functions

Returns a list of the names of all the functions in the class's immediate namespace. note that this is not the METHODS of the class, just the functions. Returns a reference to an array of the function names on success.

Returns undef on error or if the class is not loaded.

---

function_refs

Returns a list of references to all the functions in the class's immediate namespace.

Returns a reference to an array of CODE refs of the functions on success, or undef on error or if the class is not loaded.

---

function_exists $function

checks to see if the function exists in the class. note that this is as a function, not as a method. to see if a method exists for a class, use the can method in UNIVERSAL, and hence to every other class. iykyk. 💅

Returns true if the function exists, false if the function does not exist, or undef on error, or if the class is not loaded.

---

methods @options

attempts to find the methods available to the class. this includes everything in the class's super path up to, but NOT including, UNIVERSAL. Returns a reference to an array of the names of all the available methods on success. Returns undef if the class is not loaded.

any provided options are passed through, and alter the response in the same way as for the options to <Class::Inspector->methods()>, that is, 'public', 'private', 'full' and 'expanded', and combinations thereof. mix and match bestie 🎨

---

subclasses

the subclasses method will search the entire namespace (and thus all currently loaded classes) to find all of the subclasses of the class handle. it's doing a full sweep. 🔎

the actual test will be done by calling isa on the class as a static method. (i.e. <My::Class->isa($class)>).

Returns a reference to a list of the names of the loaded classes that match the class provided, or false if none match, or undef if the class name provided is invalid.

---

super_path

the super_path method is a straight pass through to the Class::ISA::super_path function. Returns an ordered list of class names, with no duplicates. the list does NOT include the class itself, or the UNIVERSAL class. no selfies allowed in this list. 🙅

---

self_and_super_path

as above, but includes ourself at the beginning of the path. directly passes through to Class::ISA. okay so this one allows selfies. 📸

---

full_super_path

the full_super_path method is an additional method not in Class::ISA. it returns as for super_path, except that it also contains BOTH the class itself, and UNIVERSAL. this full list is more technically accurate, but less commonly used, and as such isn't available from Class::ISA itself. the deluxe edition, basically. 👑

---

💀 BUGS 💀

No known bugs. Additional feature requests are being taken. (we're accepting applications bestie, come thru 🫶)

---

🩷 SUPPORT 🩷

Bugs should be reported via the CPAN bug tracking system:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Handle>

For other inquiries, contact the author.

---

🌟 AUTHOR 🌟

Adam Kennedy <adamk@cpan.org>, <http://ali.as/>

---

🔥 SEE ALSO 🔥

UNIVERSAL, Class::ISA, and Class::Inspector, which provide most of the functionality for this class. the whole friend group, basically. 🌈

---

📜 COPYRIGHT 📜

Copyright (c) 2002 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

okay and that's the whole page bestie, we ate and left no crumbs 💅✨ this was perl v5.36.0, dated 2022-12-17, and it's the Class::Handle(3pm) page — go forth and handle your classes, you've got this 🫶🎀🦋