Take me over?
NAME
Class::Fields - Inspect the fields of a class.
SYNOPSIS
use
Class::Fields;
is_field (
$class
,
$field
);
is_public (
$class
,
$field
);
is_private (
$class
,
$field
);
is_protected(
$class
,
$field
);
is_inherited(
$class
,
$field
);
@fields
= show_fields(
$class
,
@attribs
);
$attrib
= field_attrib_mask(
$class
,
$field
);
@attribs
= field_attribs(
$class
,
$field
);
dump_all_attribs(
@classes
);
# All functions also work as methods.
package
Foo;
Foo->is_public(
$field
);
@fields
= Foo->show_fields(
@attribs
);
# ...etc...
DESCRIPTION
NOTE This module, and the fields system, is largely obsolete. Please consider using one of the many accessor generating modules, or just skip directly to a complete object oriented system like Moose or Mouse.
A collection of utility functions/methods for examining the data members of a class. It provides a nice, high-level interface that should stand the test of time and Perl upgrades nicely.
The functions in this module also serve double-duty as methods and can be used that way by having your module inherit from it. For example:
package
Foo;
"'_whatever' is a private data member of 'Foo'"
if
Foo->is_private(
'_whatever'
);
# Let's assume we have a new() method defined for Foo, okay?
$obj
= Foo->new;
"'this' is a public data member of 'Foo'"
if
$obj
->is_public(
'this'
);
- is_field
-
is_field(
$class
,
$field
);
$class
->is_field(
$field
);
Simply asks if a given $class has the given $field defined in it.
- is_public
- is_private
- is_protected
- is_inherited
-
is_public(
$class
,
$field
);
is_private(
$class
,
$field
);
...etc...
or
$obj
->is_public(
$field
);
or
Class->is_public(
$field
);
A bunch of functions to quickly check if a given $field in a given $class is of a given type. For example...
- show_fields
-
@all_fields
= show_fields(
$class
);
@fields
= show_fields(
$class
,
@attribs
);
or
@all_fields
=
$obj
->show_fields;
@fields
=
$obj
->show_fields(
@attribs
);
or
@all_fields
= Class->show_fields;
@fields
= Class->show_fields(
@attribs
);
This will list all fields in a given $class that have the given set of @attribs. If @attribs is not given it will simply list all fields.
The currently available attributes are: Public, Private, Protected and Inherited
For example:
package
Foo;
package
Bar;
use
Class::Fields;
# @fields contains 'this', 'that' and 'meme' since they are Public and
# Inherited. It doesn't contain 'salmon' since while it is
# Public it is not Inherited.
@fields
= show_fields(
'Bar'
,
qw(Public Inherited)
);
- field_attrib_mask
-
$attrib
= field_attrib_mask(
$class
,
$field
);
or
$attrib
=
$obj
->field_attrib_mask(
$field
);
or
$attrib
= Class->field_attrib_mask(
$field
);
It will tell you the numeric attribute for the given $field in the given $class. $attrib is a bitmask which must be interpreted with the PUBLIC, PRIVATE, etc... constants from Class::Fields::Attrib.
field_attribs() is probably easier to work with in general.
- field_attribs
-
@attribs
= field_attribs(
$class
,
$field
);
or
@attribs
=
$obj
->field_attribs(
$field
);
or
@attribs
= Class->field_attribs(
$field
);
Exactly the same as field_attrib_mask(), except that instead of returning a bitmask it returns a somewhat friendlier list of attributes which are applied to this field. For example...
The attributes returned are the same as those taken by show_fields().
- dump_all_attribs
-
dump_all_attribs;
dump_all_attribs(
@classes
);
or
Class->dump_all_attribs;
or
$obj
->dump_all_attribs;
A debugging tool which simply prints to STDERR everything it can about a given set of @classes in a relatively formated manner.
Alas, this function works slightly differently if used as a function as opposed to a method:
When called as a function it will print out attribute information about all @classes given. If no @classes are given it will print out the attributes of -every- class it can find that has attributes.
When uses as a method, it will print out attribute information for the class or object which uses the method. No arguments are accepted.
I'm not entirely happy about this split and I might change it in the future.
EXAMPLES
Neat tricks that can be done with this module:
- An integrity check for your object.
-
Upon destruction, check to make sure no strange keys were added to your object hash. This is a nice check against typos and other modules sticking their dirty little fingers where they shouldn't be if you're not using a pseudo-hash.
sub
DESTROY {
my
(
$self
) =
@_
;
my
(
$class
) =
ref
$self
;
my
%fields
=
map
{ (
$_
,1) }
$self
->show_fields;
foreach
my
$key
(
keys
%$self
) {
warn
"Strange key '$key' found in object '$self' "
.
"of class '$class'"
unless
exists
$fields
{
$key
};
}
}
- Autoloaded accessors for public data members.
-
Proper OO dogma tells you to do all public data access through accessors (methods who's sole purpose is to get and set data in your object). This can be a royal pain in the ass to write and can also get rapidly unmaintainable since you wind up with a series of nearly identical methods.
*Perfect* for an autoloader!
package
Test::Autoload::Example;
sub
AUTOLOAD {
my
$self
=
$_
[0];
my
$class
=
ref
$self
;
my
(
$field
) =
$AUTOLOAD
=~ /::([^:]+)$/;
return
if
$field
eq
'DESTROY'
;
# If its a public field, set up a named closure as its
# data accessor.
if
(
$self
->is_public(
$field
) ) {
*{
$class
.
"::$field"
} =
sub
{
my
(
$self
) =
shift
;
if
(
@_
) {
$self
->{
$field
} =
shift
;
}
return
$self
->{
$field
};
};
goto
&{
$class
.
"::$field"
};
}
else
{
die
"'$field' is not a public data member of '$class'"
;
}
}
"EXAMPLES" in Class::Accessor for a much simpler version of this same technique.
COPYRIGHT AND LICENSE
Copyright 2001-2011 by Michael G Schwern <schwern@pobox.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://dev.perl.org/licenses/artistic.html
AUTHOR
Michael G Schwern <schwern@pobox.com> with much code liberated from the original fields.pm.
THANKS
Thanks to Tels for his big feature request/bug report.
SEE ALSO
This module and the fields system are obsolete. Moose, Mouse, Class::Accessor are better alternatives.
fields, public, private, protected
Modules with similar effects... Tie::SecureHash
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 386:
You forgot a '=back' before '=head1'