1package Class::Handle; 2 3=pod 4 5=head1 NAME 6 7Class::Handle - Create objects that are handles to Classes 8 9=head1 SYNOPSIS 10 11 # Create a class handle 12 use Class::Handle; 13 my $class = Class::Handle->new( 'Foo::Class' ); 14 my $name = $class->name; 15 16 # UNIVERSAL type methods 17 $class->VERSION(); 18 $class->isa( 'Foo:Bar' ); 19 $class->can( 'blah' ); 20 21 # Class::Inspector type methods 22 $class->installed(); 23 $class->loaded(); 24 $class->filename(); 25 $class->resolved_filename(); 26 $class->functions(); 27 $class->function_refs(); 28 $class->function_exists( 'function' ); 29 $class->methods( 'public', 'full' ); 30 $class->subclasses(); 31 32 # Class::ISA type methods 33 $class->super_path(); 34 $class->self_and_super_path(); 35 $class->full_super_path(); 36 37 # Loading and unloading 38 $class->load(); 39 40=head1 DESCRIPTION 41 42Class related functionality in Perl is broken up into a variety of different 43modules. Class::Handle attempts to provide a convenient object wrapper around 44the various different types of functions that can be performed on a class. 45 46Please note that this is an initial non-production quality release, and should 47be used as such. Functionality and API are subject to change without notice. 48 49Currently, Class::Handle provies what is effectively a combined API from 50C<UNIVERSAL>, C<Class::ISA> and C<Class::Inspector> for obtaining information 51about a Class, and some additional task methods, such as C<load> to common 52tasks relating to classes. 53 54=head1 UNIVERSAL API 55 56To ensure we maintain compliance with other classes that rely on 57methods provided by C<UNIVERSAL>, Class::Handle acts in the normal way when 58something like C<<Class::Handle->VERSION>> is called. That is, it returns the 59version of Class::Handle itself. When C<UNIVERSAL> methods are called on 60an instantiation the method is changed to act on the class we have a handle 61to. For example, the two following statements are equivalent. 62 63 # Getting the version directly 64 print Foo::Bar->VERSION; 65 66 # Getting the version via Class::Handle 67 my $class = Class::Handle->new( 'Foo::Bar' ); 68 print $class->VERSION; 69 70This also applies to the C<isa> and C<can> methods. 71 72=head1 METHODS 73 74=cut 75 76use 5.005; 77use strict; 78use UNIVERSAL (); 79use Class::ISA (); 80use Class::Inspector (); 81 82# Set the version 83use vars qw{$VERSION}; 84BEGIN { 85 $VERSION = '1.07'; 86} 87 88 89 90 91 92##################################################################### 93# Constructor 94 95=pod 96 97=head2 new $class 98 99The C<new> constructor will create a new handle to a class or unknown 100existance or status. That is, it won't check that the class actually exists 101at this time. It WILL however check to make sure that your class name is legal. 102 103 Returns a new Class::Handle object on success 104 Returns undef if the class name is illegal 105 106=cut 107 108sub new { 109 my $class = ref $_[0] ? ref shift : shift; 110 111 # Get and check the class name 112 my $name = shift or return undef; 113 $name = 'main' if $name eq '::'; 114 $name =~ s/^::/main::/; 115 return undef unless $name =~ /^[a-z]\w*((?:'|::)\w+)*$/io; 116 117 # Create and return the object 118 bless { name => $name }, $class; 119} 120 121=pod 122 123=head2 name 124 125The c<name> method returns the name of the class as original specified in 126the constructor. 127 128=cut 129 130sub name { $_[0]->{name} } 131 132 133 134 135 136##################################################################### 137# UNIVERSAL Methods 138 139=pod 140 141=head2 VERSION 142 143Find the version for the class. Does not check that the class is loaded ( at 144this time ). 145 146Returns the version on success, C<undef> if the class does not defined a 147C<$VERSION> or the class is not loaded. 148 149=cut 150 151sub VERSION { 152 my $either = shift; 153 154 # In the special case that someone wants to know OUR version, 155 # let them find it out as normal. Otherwise, return the VERSION 156 # for the class we point to. 157 ref $either 158 ? UNIVERSAL::VERSION( $either->{name} ) 159 : UNIVERSAL::VERSION( $either ); 160} 161 162=pod 163 164=head2 isa $class 165 166Checks to see if the class is a subclass of another class. Does not check that 167the class is loaded ( at this time ). 168 169Returns true/false as for C<UNIVERSAL::isa> 170 171=cut 172 173sub isa { 174 my $either = shift; 175 my $isa = shift or return undef; 176 177 # In the special case that someone wants to know an isa for 178 # OUR version, let them find it out as normal. Otherwise, return 179 # the isa for the class we point to. 180 ref $either 181 ? UNIVERSAL::isa( $either->{name}, $isa ) 182 : UNIVERSAL::isa( $either, $isa ); 183} 184 185=pod 186 187=head2 can $method 188 189Checks to see if a particular method is defined for the class. 190 191Returns a C<CODE> ref to the function is the method is available, 192or false if the class does not have that method available. 193 194=cut 195 196sub can { 197 my $either = shift; 198 my $can = shift or return undef; 199 200 # In the special case that someone wants to know a "cab" for 201 # OUR versoin, let them find it out as normal. Otherwise, return 202 # the can for the class we point to. 203 ref $either 204 ? UNIVERSAL::can( $either->{name}, $can ) 205 : UNIVERSAL::can( $either, $can ); 206} 207 208 209 210 211 212##################################################################### 213# Class::Inspector methods 214 215=pod 216 217=head2 installed 218 219Checks to see if a particular class is installed on the machine, or at least 220that the class is available to perl. In this case, "class" really means 221"module". This methods cannot detect a class that is not a module. ( Has its 222own file ). 223 224Returns true if the class is installed and available, or false otherwise. 225 226=cut 227 228sub installed { 229 my $self = ref $_[0] ? shift : return undef; 230 Class::Inspector->installed( $self->{name} ); 231} 232 233=pod 234 235=head2 loaded 236 237Checks to see if a class is loaded. In this case, "class" does NOT mean 238"module". The C<loaded> method will return true for classes that do not have 239their own file. 240 241For example, if a module C<Foo> contains the classes C<Foo>, C<Foo::Bar> and 242C<Foo::Buffy>, the C<loaded> method will return true for all of the classes. 243 244Returns true if the class is loaded, or false otherwise. 245 246=cut 247 248sub loaded { 249 my $self = ref $_[0] ? shift : return undef; 250 Class::Inspector->loaded( $self->{name} ); 251} 252 253=pod 254 255=head2 filename 256 257Returns the base filename for a class. For example, for the class 258C<Foo::Bar>, C<loaded> would return C<"Foo/Bar.pm">. 259 260The C<filename> method is platform neutral, it should always return the 261filename in the correct format for your platform. 262 263=cut 264 265sub filename { 266 my $self = ref $_[0] ? shift : return undef; 267 Class::Inspector->filename( $self->{name} ); 268} 269 270=pod 271 272=head2 resolved_filename @extra_paths 273 274The C<resolved_filename> will attempt to find the real file on your system 275that will be used when a class is loaded. If additional paths are provided 276as argument, they will be tried first, before the contents of the @INC array. 277If a file cannot be found to match the class, returns false. 278 279=cut 280 281sub resolved_filename { 282 my $self = ref $_[0] ? shift : return undef; 283 Class::Inspector->resolved_filename( $self->{name} ); 284} 285 286=pod 287 288=head2 loaded_filename 289 290If the class is loaded, returns the name of the file that it was originally 291loaded from. 292 293Returns false if the class is not loaded, or did not have its own file. 294 295=cut 296 297sub loaded_filename { 298 my $self = ref $_[0] ? shift : return undef; 299 Class::Inspector->loaded_filename( $self->{name} ); 300} 301 302=pod 303 304=head2 functions 305 306Returns a list of the names of all the functions in the classes immediate 307namespace. Note that this is not the METHODS of the class, just the functions. 308Returns a reference to an array of the function names on success. 309 310Returns undef on error or if the class is not loaded. 311 312=cut 313 314sub functions { 315 my $self = ref $_[0] ? shift : return undef; 316 Class::Inspector->functions( $self->{name} ); 317} 318 319=pod 320 321=head2 function_refs 322 323Returns a list of references to all the functions in the classes immediate 324namespace. 325 326Returns a reference to an array of CODE refs of the functions on 327success, or C<undef> on error or if the class is not loaded. 328 329=cut 330 331sub function_refs { 332 my $self = ref $_[0] ? shift : return undef; 333 Class::Inspector->function_refs( $self->{name} ); 334} 335 336=pod 337 338=head2 function_exists $function 339 340Checks to see if the function exists in the class. Note that this is as a 341function, not as a method. To see if a method exists for a class, use the 342C<can> method in UNIVERSAL, and hence to every other class. 343 344Returns true if the function exists, false if the function does not exist, 345or C<undef> on error, or if the class is not loaded. 346 347=cut 348 349sub function_exists { 350 my $self = ref $_[0] ? shift : return undef; 351 Class::Inspector->function_exists( $self->{name}, @_ ); 352} 353 354=pod 355 356=head2 methods @options 357 358Attempts to find the methods available to the class. This includes everything 359in the classes super path up to, but NOT including, UNIVERSAL. Returns a 360reference to an array of the names of all the available methods on success. 361Returns undef if the class is not loaded. 362 363Any provided options are passed through, and alter the response in the same 364way as for the options to C<<Class::Inspector->methods()>>, that is, 'public', 365'private', 'full' and 'expanded', and combinations thereof. 366 367=cut 368 369sub methods { 370 my $self = ref $_[0] ? shift : return undef; 371 Class::Inspector->methods( $self->{name}, @_ ); 372} 373 374=pod 375 376=head2 subclasses 377 378The C<subclasses> method will search then entire namespace (and thus 379B<all> currently loaded classes) to find all of the subclasses of the 380class handle. 381 382The actual test will be done by calling C<isa> on the class as a static 383method. (i.e. C<<My::Class->isa($class)>>. 384 385Returns a reference to a list of the names of the loaded classes that match 386the class provided, or false is none match, or C<undef> if the class name 387provided is invalid. 388 389=cut 390 391sub subclasses { 392 my $self = ref $_[0] ? shift : return undef; 393 Class::Inspector->subclasses( $self->{name}, @_ ); 394} 395 396 397 398 399 400##################################################################### 401# Class::ISA Methods 402 403=pod 404 405=head2 super_path 406 407The C<super_path> method is a straight pass through to the 408C<Class::ISA::super_path> function. Returns an ordered list of 409class names, with no duplicates. The list does NOT include the class itself, 410or the L<UNIVERSAL> class. 411 412=cut 413 414sub super_path { 415 my $self = ref $_[0] ? shift : return undef; 416 Class::ISA::super_path( $self->{name} ); 417} 418 419=pod 420 421=head2 self_and_super_path 422 423As above, but includes ourself at the beginning of the path. Directly 424passes through to L<Class::ISA>. 425 426=cut 427 428sub self_and_super_path { 429 my $self = ref $_[0] ? shift : return undef; 430 Class::ISA::self_and_super_path( $self->{name} ); 431} 432 433=pod 434 435=head2 full_super_path 436 437The C<full_super_path> method is an additional method not in C<Class::ISA>. 438It returns as for C<super_path>, except that it also contains BOTH the 439class itself, and C<UNIVERSAL>. This full list is more technically accurate, 440but less commonly used, and as such isn't available from L<Class::ISA> 441itself. 442 443=cut 444 445sub full_super_path { 446 my $self = ref $_[0] ? shift : return (); 447 Class::ISA::self_and_super_path( $self->{name} ), 'UNIVERSAL'; 448} 449 450 451 452 453 454 455##################################################################### 456# Task Methods 457 458# These methods are specific to Class::Handle and provide simpler 459# interfaces to common tasks. 460 461# Run-time load a class, as if it were a C<use>, including import. 462# Roughly equivalent to require $name; $name->import; 463sub load { 464 my $self = shift or return undef; 465 466 # Shortcut if the class is already loaded 467 return 1 if Class::Inspector->loaded( $self->{name} ); 468 469 # Get the resolved file name 470 my $filename = $self->resolved_filename() or return undef; 471 472 # Load the class 473 require $filename or return undef; 474 475 # Do we need to call an import method? 476 my $import = $self->can( 'import' ) or return 1; 477 478 # Go to the import 479 goto &{$import}; 480} 481 4821; 483 484=pod 485 486=head1 BUGS 487 488No known bugs. Additional feature requests are being taken. 489 490=head1 SUPPORT 491 492Bugs should be reported via the CPAN bug tracking system 493 494L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Handle> 495 496For other inquiries, contact the author 497 498=head1 AUTHOR 499 500Adam Kennedy E<lt>adamk@cpan.orgE<gt>, L<http://ali.as/> 501 502=head1 SEE ALSO 503 504C<UNIVERSAL>, C<Class::ISA>, and C<Class::Inspector>, which provide 505most of the functionality for this class. 506 507=head1 COPYRIGHT 508 509Copyright (c) 2002 - 2006 Adam Kennedy. 510 511This program is free software; you can redistribute 512it and/or modify it under the same terms as Perl itself. 513 514The full text of the license can be found in the 515LICENSE file included with this module. 516 517=cut 518