NAME¶
Class::MOP::Attribute - Attribute Meta Object
VERSION¶
version 2.1213
SYNOPSIS¶
Class::MOP::Attribute->new(
foo => (
accessor => 'foo', # dual purpose get/set accessor
predicate => 'has_foo', # predicate check for defined-ness
init_arg => '-foo', # class->new will look for a -foo key
default => 'BAR IS BAZ!' # if no -foo key is provided, use this
)
);
Class::MOP::Attribute->new(
bar => (
reader => 'bar', # getter
writer => 'set_bar', # setter
predicate => 'has_bar', # predicate check for defined-ness
init_arg => ':bar', # class->new will look for a :bar key
# no default value means it is undef
)
);
DESCRIPTION¶
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.
METHODS¶
Creation¶
- Class::MOP::Attribute->new($name, ?%options)
- 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:
Class::MOP::Attribute->new(
'foo' => (
default => sub { [] },
)
);
# or ...
Class::MOP::Attribute->new(
'foo' => (
default => sub { {} },
)
);
If you wish to initialize an attribute with a subroutine reference itself,
then you need to wrap that in a subroutine as well:
Class::MOP::Attribute->new(
'foo' => (
default => sub {
sub { print "Hello World" }
},
)
);
And lastly, if the value of your attribute is dependent upon some other
aspect of the instance structure, then you can take advantage of the fact
that when the "default" value is called as a method:
Class::MOP::Attribute->new(
'object_identity' => (
default => sub { Scalar::Util::refaddr( $_[0] ) },
)
);
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.
Class::MOP::Attribute->new(
'doubled' => (
initializer => sub {
my ( $self, $value, $set, $attr ) = @_;
$set->( $value * 2 );
},
)
);
Since an initializer can be a method name, you can easily make attribute
initialization use the writer:
Class::MOP::Attribute->new(
'some_attr' => (
writer => 'some_attr',
initializer => 'some_attr',
)
);
Your writer (actually, a wrapper around the writer, using method
modifications) will need to examine @_ and determine under which context
it is being called:
around 'some_attr' => sub {
my $orig = shift;
my $self = shift;
# $value is not defined if being called as a reader
# $setter and $attr are only defined if being called as an initializer
my ($value, $setter, $attr) = @_;
# the reader behaves normally
return $self->$orig if not @_;
# mutate $value as desired
# $value = <something($value);
# if called as an initializer, set the value and we're done
return $setter->($row) if $setter;
# otherwise, call the real writer with the new value
$self->$orig($row);
};
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.
- $attr->clone(%options)
- This clones the attribute. Any options you provide will override the
settings of the original attribute. You can change the name of the new
attribute by passing a "name" key in %options.
These are all basic read-only accessors for the values passed into the
constructor.
- $attr->name
- Returns the attribute's name.
- $attr->accessor
- $attr->reader
- $attr->writer
- $attr->predicate
- $attr->clearer
- The "accessor", "reader", "writer",
"predicate", and "clearer" methods all return exactly
what was passed to the constructor, so it can be either a string
containing a method name, or a hash reference.
- $attr->initializer
- Returns the initializer as passed to the constructor, so this may be
either a method name or a subroutine reference.
- $attr->init_arg
- $attr->is_default_a_coderef
- $attr->builder
- $attr->default($instance)
- The $instance argument is optional. If you don't pass it, the return value
for this method is exactly what was passed to the constructor, either a
simple scalar or a subroutine reference.
If you do pass an $instance and the default is a subroutine
reference, then the reference is called as a method on the $instance and
the generated value is returned.
- $attr->slots
- Return a list of slots required by the attribute. This is usually just
one, the name of the attribute.
A slot is the name of the hash key used to store the attribute in an object
instance.
- $attr->get_read_method
- $attr->get_write_method
- Returns the name of a method suitable for reading or writing the value of
the attribute in the associated class.
If an attribute is read- or write-only, then these methods can return
"undef" as appropriate.
- $attr->has_read_method
- $attr->has_write_method
- This returns a boolean indicating whether the attribute has a named
read or write method.
- $attr->get_read_method_ref
- $attr->get_write_method_ref
- 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.
- $attr->insertion_order
- If this attribute has been inserted into a class, this returns a zero
based index regarding the order of insertion.
These are all basic predicate methods for the values passed into
"new".
- $attr->has_accessor
- $attr->has_reader
- $attr->has_writer
- $attr->has_predicate
- $attr->has_clearer
- $attr->has_initializer
- $attr->has_init_arg
- This will be false if the "init_arg" was set to
"undef".
- $attr->has_default
- This will be false if the "default" was set to
"undef", since "undef" is the default
"default" anyway.
- $attr->has_builder
- $attr->has_insertion_order
- This will be false if this attribute has not be inserted into a
class
Value management¶
These methods are basically "back doors" to the instance, and can be
used to bypass the regular accessors, but still stay within the MOP.
These methods are not for general use, and should only be used if you really
know what you are doing.
- $attr->initialize_instance_slot($meta_instance,
$instance, $params)
- This method is used internally to initialize the attribute's slot in the
object $instance.
The $params is a hash reference of the values passed to the object
constructor.
It's unlikely that you'll need to call this method yourself.
- $attr->set_value($instance,
$value)
- Sets the value without going through the accessor. Note that this works
even with read-only attributes.
- $attr->set_raw_value($instance,
$value )
- Sets the value with no side effects such as a trigger.
This doesn't actually apply to Class::MOP attributes, only to
subclasses.
- $attr->set_initial_value($instance,
$value )
- Sets the value without going through the accessor. This method is only
called when the instance is first being initialized.
- $attr->get_value($instance)
- Returns the value without going through the accessor. Note that this works
even with write-only accessors.
- $attr->get_raw_value($instance)
- Returns the value without any side effects such as lazy attributes.
Doesn't actually apply to Class::MOP attributes, only to subclasses.
- $attr->has_value($instance)
- Return a boolean indicating whether the attribute has been set in
$instance. This how the default "predicate" method works.
- $attr->clear_value($instance)
- This will clear the attribute's value in $instance. This is what the
default "clearer" calls.
Note that this works even if the attribute does not have any associated
read, write or clear methods.
Class association¶
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.
- $attr->associated_class
- This returns the Class::MOP::Class with which this attribute is
associated, if any.
- $attr->attach_to_class($metaclass)
- This method stores a weakened reference to the $metaclass object
internally.
This method does not remove the attribute from its old class, nor does it
create any accessors in the new class.
It is probably best to use the Class::MOP::Class "add_attribute"
method instead.
- $attr->detach_from_class
- This method removes the associate metaclass object from the attribute it
has one.
This method does not remove the attribute itself from the class, or remove
its accessors.
It is probably best to use the Class::MOP::Class
"remove_attribute" method instead.
Attribute Accessor generation¶
- $attr->accessor_metaclass
- Accessor methods are generated using an accessor metaclass. By default,
this is Class::MOP::Method::Accessor. This method returns the name of the
accessor metaclass that this attribute uses.
- $attr->associate_method($method)
- This associates a Class::MOP::Method object with the attribute. Typically,
this is called internally when an attribute generates its accessors.
- $attr->associated_methods
- This returns the list of methods which have been associated with the
attribute.
- $attr->install_accessors
- This method generates and installs code the attributes various accessors.
It is typically called from the Class::MOP::Class
"add_attribute" method.
- $attr->remove_accessors
- This method removes all of the accessors associated with the attribute.
This does not currently remove methods from the list returned by
"associated_methods".
- $attr->inline_get
- $attr->inline_set
- $attr->inline_has
- $attr->inline_clear
- These methods return a code snippet suitable for inlining the relevant
operation. They expect strings containing variable names to be used in the
inlining, like '$self' or '$_[1]'.
Introspection¶
- Class::MOP::Attribute->meta
- This will return a Class::MOP::Class instance for this class.
It should also be noted that Class::MOP will actually bootstrap this module
by installing a number of attribute meta-objects into its metaclass.
AUTHORS¶
- •
- Stevan Little <stevan.little@iinteractive.com>
- •
- Dave Rolsky <autarch@urth.org>
- •
- Jesse Luehrs <doy@tozt.net>
- •
- Shawn M Moore <code@sartak.org>
- •
- XXXX XXX'XX (Yuval Kogman) <nothingmuch@woobling.org>
- •
- Karen Etheridge <ether@cpan.org>
- •
- Florian Ragwitz <rafl@debian.org>
- •
- Hans Dieter Pearcey <hdp@weftsoar.net>
- •
- Chris Prather <chris@prather.org>
- •
- Matt S Trout <mst@shadowcat.co.uk>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2006 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.