The Attribute Protocol is almost entirely an invention of Class::MOP. Perl 5 does not have a consistent notion of attributes. There are so many ways in which this is done, and very few (if any) are easily discoverable by this module.

With that said, this module attempts to inject some order into this chaos, by introducing a consistent API which can be used to create object attributes.

An attribute must (at the very least), have a $name. All other %options are added as key-value pairs.

init_arg

This is a string value representing the expected key in an initialization hash. For instance, if we have an init_arg value of -foo, then the following code will Just Work.

MyClass->meta->new_object( -foo => 'Hello There' );

If an init_arg is not assigned, it will automatically use the attribute's name. If init_arg is explicitly set to undef, the attribute cannot be specified during initialization.

builder

This provides the name of a method that will be called to initialize the attribute. This method will be called on the object after it is constructed. It is expected to return a valid value for the attribute.

default

This can be used to provide an explicit default for initializing the attribute. If the default you provide is a subroutine reference, then this reference will be called as a method on the object.

If the value is a simple scalar (string or number), then it can be just passed as is. However, if you wish to initialize it with a HASH or ARRAY ref, then you need to wrap that inside a subroutine reference:

Note that there is no guarantee that attributes are initialized in any particular order, so you cannot rely on the value of some other attribute when generating the default.

initializer

This option can be either a method name or a subroutine reference. This method will be called when setting the attribute's value in the constructor. Unlike default and builder, the initializer is only called when a value is provided to the constructor. The initializer allows you to munge this value during object construction.

The initializer is called as a method with three arguments. The first is the value that was passed to the constructor. The second is a subroutine reference that can be called to actually set the attribute's value, and the last is the associated Class::MOP::Attribute object.

This contrived example shows an initializer that sets the attribute to twice the given value.

Your writer will need to examine @_ and determine under which context it is being called.

The accessor, reader, writer, predicate and clearer options all accept the same parameters. You can provide the name of the method, in which case an appropriate default method will be generated for you. Or instead you can also provide hash reference containing exactly one key (the method name) and one value. The value should be a subroutine reference, which will be installed as the method itself.

accessor

An accessor is a standard Perl-style read/write accessor. It will return the value of the attribute, and if a value is passed as an argument, it will assign that value to the attribute.

Note that undef is a legitimate value, so this will work:

$object->set_something(undef);

reader

This is a basic read-only accessor. It returns the value of the attribute.

writer

This is a basic write accessor, it accepts a single argument, and assigns that value to the attribute.

Note that undef is a legitimate value, so this will work:

$object->set_something(undef);

predicate

The predicate method returns a boolean indicating whether or not the attribute has been explicitly set.

Note that the predicate returns true even if the attribute was set to a false value (0 or undef).

clearer

This method will uninitialize the attribute. After an attribute is cleared, its predicate will return false.

definition_context

Mostly, this exists as a hook for the benefit of Moose.

This option should be a hash reference containing several keys which will be used when inlining the attribute's accessors. The keys should include line, the line number where the attribute was created, and either file or description.

This information will ultimately be used when eval'ing inlined accessor code so that error messages report a useful line and file name.

Returns the subroutine reference of a method suitable for reading or writing the attribute's value in the associated class. These methods always return a subroutine reference, regardless of whether or not the attribute is read- or write-only.

These methods allow you to manage the attributes association with the class that contains it. These methods should not be used lightly, nor are they very magical, they are mostly used internally and by metaclass instances.