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

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;
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 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...

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 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;
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.

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