class::fields(3)

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;
use base qw( Class::Fields );
Foo->is_public($field);
@fields = Foo->show_fields(@attribs);
# ...etc...

DESCRIPTION

A collection of utility functions/methods for examining
the data members of a class. It provides a nice, highlevel 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;
use base qw( Class::Fields );
use fields qw( this that _whatever );; print "'_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;
print "'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...: package Foo;
use public qw( Ford );
use private qw( _Nixon );; package Bar;
use base qw(Foo);; # This will print only 'Ford is public' because Ford; is a public
# field of the class Bar. _Nixon is a private field; of the class
# Foo, but it is not inherited.
print 'Ford is public' if is_public('Bar',; 'Ford');
print '_Nixon is inherited' if is_inherited('Foo',; '_Nixon');
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;
use fields qw(this that meme);; package Bar;
use Class::Fields;
use base qw(Foo);
use fields qw(salmon);; # @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 Inherit; ed));
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...: package Foo;
use fields qw( yarrow );; package Bar;
use base qw(Foo);; # @attribs will contain 'Public' and 'Inherited'
@attribs = field_attribs('Bar', 'yarrow');
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 every thing it can about a given set of @classes in a rela tively 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 -everyclass 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 stick
ing 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 ob

ject '$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 pur
pose 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;
use base qw(Class::Fields);
use public qw(this that up down);
use private qw(_left _right);

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.

AUTHOR

Michael G Schwern <schwern@pobox.com> with much code lib
erated from the original fields.pm.

THANKS

Thanks to Tels for his big feature request/bug report.

docs.sk

comprehensive documentation repository

Most Viewed