1NAME
2 Class::Inspector - Get information about a class and its structure
3
4SYNOPSIS
5 use Class::Inspector;
6
7 # Is a class installed and/or loaded
8 Class::Inspector->installed( 'Foo::Class' );
9 Class::Inspector->loaded( 'Foo::Class' );
10
11 # Filename related information
12 Class::Inspector->filename( 'Foo::Class' );
13 Class::Inspector->resolved_filename( 'Foo::Class' );
14
15 # Get subroutine related information
16 Class::Inspector->functions( 'Foo::Class' );
17 Class::Inspector->function_refs( 'Foo::Class' );
18 Class::Inspector->function_exists( 'Foo::Class', 'bar' );
19 Class::Inspector->methods( 'Foo::Class', 'full', 'public' );
20
21 # Find all loaded subclasses or something
22 Class::Inspector->subclasses( 'Foo::Class' );
23
24DESCRIPTION
25 Class::Inspector allows you to get information about a loaded class.
26 Most or all of this information can be found in other ways, but they
27 arn't always very friendly, and usually involve a relatively high level
28 of Perl wizardry, or strange and unusual looking code. Class::Inspector
29 attempts to provide an easier, more friendly interface to this
30 information.
31
32METHODS
33 installed $class
34 The "installed" static method tries to determine if a class is installed
35 on the machine, or at least available to Perl. It does this by wrapping
36 around "resolved_filename".
37
38 Returns true if installed/available, false if the class is not
39 installed, or "undef" if the class name is invalid.
40
41 loaded $class
42 The "loaded" static method tries to determine if a class is loaded by
43 looking for symbol table entries.
44
45 This method it uses to determine this will work even if the class does
46 not have its own file, but is contained inside a single file with
47 multiple classes in it. Even in the case of some sort of run-time
48 loading class being used, these typically leave some trace in the symbol
49 table, so an Autoload or Class::Autouse-based class should correctly
50 appear loaded.
51
52 Returns true if the class is loaded, false if not, or "undef" if the
53 class name is invalid.
54
55 filename $class
56 For a given class, returns the base filename for the class. This will
57 NOT be a fully resolved filename, just the part of the filename BELOW
58 the @INC entry.
59
60 print Class->filename( 'Foo::Bar' );
61 > Foo/Bar.pm
62
63 This filename will be returned with the right seperator for the local
64 platform, and should work on all platforms.
65
66 Returns the filename on success or "undef" if the class name is invalid.
67
68 resolved_filename $class, @try_first
69 For a given class, the "resolved_filename" static method returns the
70 fully resolved filename for a class. That is, the file that the class
71 would be loaded from.
72
73 This is not nescesarily the file that the class WAS loaded from, as the
74 value returned is determined each time it runs, and the @INC include
75 path may change.
76
77 To get the actual file for a loaded class, see the "loaded_filename"
78 method.
79
80 Returns the filename for the class, or "undef" if the class name is
81 invalid.
82
83 loaded_filename $class
84 For a given loaded class, the "loaded_filename" static method determines
85 (via the %INC hash) the name of the file that it was originally loaded
86 from.
87
88 Returns a resolved file path, or false if the class did not have it's
89 own file.
90
91 functions $class
92 For a loaded class, the "functions" static method returns a list of the
93 names of all the functions in the classes immediate namespace.
94
95 Note that this is not the METHODS of the class, just the functions.
96
97 Returns a reference to an array of the function names on success, or
98 "undef" if the class name is invalid or the class is not loaded.
99
100 function_refs $class
101 For a loaded class, the "function_refs" static method returns references
102 to all the functions in the classes immediate namespace.
103
104 Note that this is not the METHODS of the class, just the functions.
105
106 Returns a reference to an array of "CODE" refs of the functions on
107 success, or "undef" if the class is not loaded.
108
109 function_exists $class, $function
110 Given a class and function name the "function_exists" static method will
111 check to see if the function exists in the class.
112
113 Note that this is as a function, not as a method. To see if a method
114 exists for a class, use the "can" method for any class or object.
115
116 Returns true if the function exists, false if not, or "undef" if the
117 class or function name are invalid, or the class is not loaded.
118
119 methods $class, @options
120 For a given class name, the "methods" static method will returns ALL the
121 methods available to that class. This includes all methods available
122 from every class up the class' @ISA tree.
123
124 Returns a reference to an array of the names of all the available
125 methods on success, or "undef" if the class name is invalid or the class
126 is not loaded.
127
128 A number of options are available to the "methods" method that will
129 alter the results returned. These should be listed after the class name,
130 in any order.
131
132 # Only get public methods
133 my $method = Class::Inspector->methods( 'My::Class', 'public' );
134
135 public
136 The "public" option will return only 'public' methods, as defined by
137 the Perl convention of prepending an underscore to any 'private'
138 methods. The "public" option will effectively remove any methods
139 that start with an underscore.
140
141 private
142 The "private" options will return only 'private' methods, as defined
143 by the Perl convention of prepending an underscore to an private
144 methods. The "private" option will effectively remove an method that
145 do not start with an underscore.
146
147 Note: The "public" and "private" options are mutually exclusive
148
149 full
150 "methods" normally returns just the method name. Supplying the
151 "full" option will cause the methods to be returned as the full
152 names. That is, instead of returning "[ 'method1', 'method2',
153 'method3' ]", you would instead get "[ 'Class::method1',
154 'AnotherClass::method2', 'Class::method3' ]".
155
156 expanded
157 The "expanded" option will cause a lot more information about method
158 to be returned. Instead of just the method name, you will instead
159 get an array reference containing the method name as a single
160 combined name, ala "full", the seperate class and method, and a CODE
161 ref to the actual function ( if available ). Please note that the
162 function reference is not guarenteed to be available.
163 "Class::Inspector" is intended at some later time, work with modules
164 that have some some of common run-time loader in place ( e.g
165 "Autoloader" or "Class::Autouse" for example.
166
167 The response from "methods( 'Class', 'expanded' )" would look
168 something like the following.
169
170 [
171 [ 'Class::method1', 'Class', 'method1', \&Class::method1 ],
172 [ 'Another::method2', 'Another', 'method2', \&Another::method2 ],
173 [ 'Foo::bar', 'Foo', 'bar', \&Foo::bar ],
174 ]
175
176 subclasses $class
177 The "subclasses" static method will search then entire namespace (and
178 thus all currently loaded classes) to find all classes that are
179 subclasses of the class provided as a the parameter.
180
181 The actual test will be done by calling "isa" on the class as a static
182 method. (i.e. "My::Class->isa($class)".
183
184 Returns a reference to a list of the loaded classes that match the class
185 provided, or false is none match, or "undef" if the class name provided
186 is invalid.
187
188TO DO
189 - Adding Class::Inspector::Functions
190
191SUPPORT
192 Bugs should be reported via the CPAN bug tracker
193
194 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Inspector>
195
196 For other issues, or commercial enhancement or support, contact the
197 author.
198
199AUTHOR
200 Adam Kennedy <cpan@ali.as>
201
202SEE ALSO
203 <http://ali.as/>, Class::Handle
204
205COPYRIGHT
206 Copyright (c) 2002 - 2006 Adam Kennedy. All rights reserved.
207
208 This program is free software; you can redistribute it and/or modify it
209 under the same terms as Perl itself.
210
211 The full text of the license can be found in the LICENSE file included
212 with this module.
213
214