Class::Fields - Inspect the fields of a class.


Class::Fields - Inspect the fields of a class.


    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);
    # All functions also work as methods.
    package Foo;
    use base qw( Class::Fields );
    @fields = Foo->show_fields(@attribs);
    # ...etc...


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
    # 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
  is_field($class, $field);

Simply asks if a given $class has the given $field defined in it.

  is_public($class, $field);
  is_private($class, $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');
  @all_fields   = show_fields($class);
  @fields       = show_fields($class, @attribs);
  @all_fields   = $obj->show_fields;
  @fields       = $obj->show_fields(@attribs);
  @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));
  $attrib = field_attrib_mask($class, $field);
  $attrib = $obj->field_attrib_mask($field);
  $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.

  @attribs = field_attribs($class, $field);
  @attribs = $obj->field_attribs($field);
  @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().


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.


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 the Class::Accessor manpage for a much simpler version of this same technique.


Michael G Schwern <> with much code liberated from the original


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


the fields manpage, public, private, protected

Modules with similar effects... the Tie::SecureHash manpage, the Class::Contract manpage

 Class::Fields - Inspect the fields of a class.