NAME

  Class::Fields::Fuxor - Low level manipuation of object data members

SYNOPSIS

  # As functions.
  use Class::Fields::Fuxor;
  add_fields($class, $attrib, @fields);
  add_field_set($class, \@fields, \@attribs);
  has_fields($class);
  $fields = get_fields($class);
  $fattr  = get_attr($class);
  # As methods.
  package Foo;
  use base qw( Class::Fields::Fuxor );
  Foo->add_fields($attrib, @fields);
  Foo->has_fields;
  $fields   = Foo->get_fields;
  $fattr    = Foo->get_attr;
  

DESCRIPTION

This is a module for low level manipuation of the %FIELDS hash and its accompying %fields::attr hash without actually touching them. Modules like fields.pm, base.pm and public.pm make use of this module.

%FIELDS and %fields::attr are currently used to store information about the data members of classes. Since the current data inheritance system, built around pseudo-hashes, is considered a bit twitchy, it is wise to encapsulate and rope it off in the expectation that it will be replaced with something better.

Typically one does not want to mess with this stuff and instead uses fields.pm and friends or perhaps Class::Fields.

add_fields
  add_fields($class, $attrib, @fields);

Adds a bunch of @fields to the given $class using the given $attrib. For example:

    # Add the public fields 'this' and 'that' to the class Foo.
    use Class::Fields::Attribs;
    add_fields('Foo', PUBLIC, qw(this that));

$attrib is built from the constants in Class::Fields::Attribs

add_field_set
  add_field_set($class, \@fields, \@attribs);

Functionally similar to add_fields(), excepting that it can add a group of fields with different attributes all at once. This is necessary for the proper functioning of fields.pm.

Each element in @fields matches up with one in @attribs. Obviously, the two arrays must be the same size.

has_fields
  has_fields($class);

A simple check to see if the given $class has a %FIELDS hash defined. A simple test like (defined %{"$class\::FIELDS"}) will sometimes produce typo warnings because it would create the hash if it was not present before.

get_attr
  $fattr = get_attr($class);

Get's the field attribute array for the given $class. This is roughly equivalent to $fields::attr{$class} but we put a nice wrapper around it for compatibility and readability.

$fattr is an array reference containing the attributes of the fields in the given $class. Each entry in $fattr corresponds to the position indicated by the $class's %FIELDS has. For example:

    package Foo;
    use fields qw(this _that);
    $fattr = get_attr('Foo');
    # Get the attributes for '_that' in the class 'Foo'.
    $that_attribs = print $fattr->[$Foo::FIELDS->{_that}];

When possible, one should avoid using this function since it exposes more implementation detail than I'd like. Class::Fields should provide most of the functionality you'll need.

get_fields
  $fields = get_fields($class);

Gets a reference to the %FIELDS hash for the given $class. It will autogenerate a %FIELDS hash if one doesn't already exist. If you don't want this behavior, be sure to check beforehand with has_fields().

When possible, one should avoid using this function since it exposes more implementation detail than I'd like. Class::Fields should provide most of the functionality you'll need.

AUTHOR

Michael G Schwern <schwern@pobox.com> based heavily on code liberated from the original fields.pm and base.pm.

SEE ALSO

fields, base, public, private, protected, Class::Fields, Class::Fields::Attribs