NAME
Class::Handle - Supply object methods 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::ISA type methods
$class->super_path();
$class->self_and_super_path();
$class->full_path();
# Loading and unloading
$class->load();DESCRIPTION
Class related functionality in Perl is broken up into a variety of different modules. Class::Handle attempts to provide a convenient object wrapper around the various different types of functions that can be performed on a class.
Please note that this is an initial non-production quality release, and should be used as such. Functionality and API are subject to change without notice.
Currently, Class::Handle provies what is effectively a combined API from UNIVERSAL, Class::ISA and Class::Inspector for obtaining information about a Class, and some additional task methods, such as load to common tasks relating to classes.
UNIVERSAL API
To ensure we maintain 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. When UNIVERSAL methods are called on an instantiation the method is changed to act on the class we have a handle to. For example, the two following statements are equivalent.
# 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.
METHODS
new( $class )
The new constructor will create a new handle to a class or unknown existance 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.
Returns a new Class::Handle object on success
Returns undef if the class name is illegal
=head2 name()The c<name> method returns the name of the class as original specified in the constructor.
VERSION()
Find the version for the class. Does not check that the class is loaded ( at this time ). Returns the version on success. Returns undef if the class does not defined 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 is the method is available. Returns 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 methods cannot detect a class that is not a module. ( Has it's own file ). Returns true if the class is installed and available. Returns 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.
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. Returns 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.
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 argument, 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 it's own file.
functions()
Returns a list of the names of all the functions in the classes 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 classes immediate namespace. Returns a reference to an array of CODE refs of the functions on success. Returns 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. Returns 1 if the function exists. Returns 0 if the function does not exist. Returns 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 classes 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.
super_path()
The super_path method is a straight pass through to the Class::ISA-super_path> method. Returns an ordered list of class names, with no duplicates. The list does NOT include the class itself, or the UNIVERSAL class.
self_and_super_path()
As above, but includes ourself at the beginning of the path. Directly passes through to Class::ISA.
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.
BUGS
No known bugs. Additional feature requests are being taken.
SUPPORT
Contact the author
AUTHOR
Adam Kennedy
cpan@ali.as
http://ali.as/SEE ALSO
UNIVERSAL, Class::ISA, and Class::Inspector, which provide most of the functionality for this class.
COPYRIGHT
Copyright (c) 2002 Adam Kennedy. All rights reserved. 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.