Class::MOP::Attribute - Attribute Meta Object |
Class::MOP::Attribute - Attribute Meta Object
version 2.1605
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 ) );
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.
$name
. All other
%options
are added as key-value pairs.
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.
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.
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
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);
Note that undef
is a legitimate value, so this will work:
$object->set_something(undef);
Note that the predicate returns true even if the attribute was set to
a false value (0
or undef
).
predicate
will return false.
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.
clone(%options)
>>name
key in %options
.
These are all basic read-only accessors for the values passed into the constructor.
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.
default($instance)
>>$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.
A slot is the name of the hash key used to store the attribute in an object instance.
If an attribute is read- or write-only, then these methods can return
undef
as appropriate.
These are all basic predicate methods for the values passed into new
.
init_arg
was set to undef
.
default
was set to undef
, since
undef
is the default default
anyway.
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.
$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.
This doesn't actually apply to Class::MOP attributes, only to subclasses.
get_value($instance)
>>get_raw_value($instance)
>>Doesn't actually apply to Class::MOP attributes, only to subclasses.
has_value($instance)
>>$instance
. This how the default predicate
method works.
clear_value($instance)
>>$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.
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.
attach_to_class($metaclass)
>>$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 the Class::MOP::Class manpage add_attribute
method instead.
This method does not remove the attribute itself from the class, or remove its accessors.
It is probably best to use the the Class::MOP::Class manpage
remove_attribute
method instead.
associate_method($method)
>>add_attribute
method.
This does not currently remove methods from the list returned by
associated_methods
.
'$self'
or '$_[1]'
.
It should also be noted that the Class::MOP manpage will actually bootstrap this module by installing a number of attribute meta-objects into its metaclass.
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.
Class::MOP::Attribute - Attribute Meta Object |